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

docs(v2): use explicit heading IDs (#4460)

Browse source
This commit is contained in:
Alexey Pyltsyn 2021-03-19 13:00:41 +03:00 • committed by GitHub
parent 962c3748ea
commit 291a72fbae
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
162 changed files with 1435 additions and 1435 deletions
Download patch file Download diff file Expand all files Collapse all files

16
website/community/resources.md
View file

@ -6,34 +6,34 @@ slug: /resources
A curated list of interesting Docusaurus community projects. A curated list of interesting Docusaurus community projects.
## Videos ## Videos {#videos}
- [F8 2019: Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE) - [F8 2019: Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE)
## Articles ## Articles {#articles}
- [Live code editing in Docusaurus](https://dev.to/mrmuhammadali/live-code-editing-in-docusaurus-ux-at-its-best-2hj1) - [Live code editing in Docusaurus](https://dev.to/mrmuhammadali/live-code-editing-in-docusaurus-ux-at-its-best-2hj1)
## Showcase ## Showcase {#showcase}
See the <a href={require('@docusaurus/useBaseUrl').default('showcase')}>showcase</a>. See the <a href={require('@docusaurus/useBaseUrl').default('showcase')}>showcase</a>.
## Community plugins ## Community plugins {#community-plugins}
### Search ### Search {#search}
- [docusaurus-plugin-lunr](https://github.com/daldridge/docusaurus-plugin-lunr) - Docusaurus v2 plugin to create a local search index for use with Lunr.js - [docusaurus-plugin-lunr](https://github.com/daldridge/docusaurus-plugin-lunr) - Docusaurus v2 plugin to create a local search index for use with Lunr.js
- [docusaurus-lunr-search](https://github.com/lelouch77/docusurus-lunr-search) - Offline Search for Docusaurus v2 - [docusaurus-lunr-search](https://github.com/lelouch77/docusurus-lunr-search) - Offline Search for Docusaurus v2
- [docusaurus-search-local](https://github.com/cmfcmf/docusaurus-search-local) - Offline/local search for Docusaurus v2 - [docusaurus-search-local](https://github.com/cmfcmf/docusaurus-search-local) - Offline/local search for Docusaurus v2
- [@easyops-cn/docusaurus-search-local](https://github.com/easyops-cn/docusaurus-search-local) - Offline/local search for Docusaurus v2 (language of zh supported) - [@easyops-cn/docusaurus-search-local](https://github.com/easyops-cn/docusaurus-search-local) - Offline/local search for Docusaurus v2 (language of zh supported)
### Integrations ### Integrations {#integrations}
- [docusaurus2-dotenv](https://github.com/jonnynabors/docusaurus2-dotenv) - A Docusaurus 2 plugin that supports dotenv and other environment variables - [docusaurus2-dotenv](https://github.com/jonnynabors/docusaurus2-dotenv) - A Docusaurus 2 plugin that supports dotenv and other environment variables
- [posthog-docusaurus](https://github.com/PostHog/posthog-docusaurus) - Integrate [PostHog](https://posthog.com/) product analytics with Docusaurus v2 - [posthog-docusaurus](https://github.com/PostHog/posthog-docusaurus) - Integrate [PostHog](https://posthog.com/) product analytics with Docusaurus v2
- [docusaurus-plugin-moesif](https://github.com/Moesif/docusaurus-plugin-moesif) - Adds [Moesif API Analytics](https://www.moesif.com/) to track user behavior and pinpoint where developers drop off in your activation funnel. - [docusaurus-plugin-moesif](https://github.com/Moesif/docusaurus-plugin-moesif) - Adds [Moesif API Analytics](https://www.moesif.com/) to track user behavior and pinpoint where developers drop off in your activation funnel.
### Features ### Features {#features}
- [docusaurus-theme-github-codeblock](https://github.com/saucelabs/docusaurus-theme-github-codeblock). A Docusaurus v2 plugin that supports referencing code examples from public GitHub repositories - [docusaurus-theme-github-codeblock](https://github.com/saucelabs/docusaurus-theme-github-codeblock). A Docusaurus v2 plugin that supports referencing code examples from public GitHub repositories
- [docusaurus-pdf](https://github.com/KohheePeace/docusaurus-pdf) - Generate documentation into PDF format - [docusaurus-pdf](https://github.com/KohheePeace/docusaurus-pdf) - Generate documentation into PDF format
@ -41,7 +41,7 @@ See the <a href={require('@docusaurus/useBaseUrl').default('showcase')}>showcase
- [docusaurus-plugin-remote-content](https://github.com/rdilweb/docusaurus-plugin-remote-content) - A Docusaurus v2 plugin that allows you to fetch content from remote sources - [docusaurus-plugin-remote-content](https://github.com/rdilweb/docusaurus-plugin-remote-content) - A Docusaurus v2 plugin that allows you to fetch content from remote sources
- [docusaurus2-graphql-doc-generator](https://github.com/edno/docusaurus2-graphql-doc-generator) - A Docusaurus v2 plugin for generating documentation from a GraphQL schema - [docusaurus2-graphql-doc-generator](https://github.com/edno/docusaurus2-graphql-doc-generator) - A Docusaurus v2 plugin for generating documentation from a GraphQL schema
## Enterprise usage ## Enterprise usage {#enterprise-usage}
- Facebook - Facebook
- Google - Google

8
website/community/support.md
View file

@ -10,11 +10,11 @@ On this page we've listed some Docusaurus-related communities that you can be a
Before participating in Docusaurus' communities, [please read our Code of Conduct](https://engineering.fb.com/codeofconduct/). We have adopted the [Contributor Covenant](https://www.contributor-covenant.org/) and we expect that all community members adhere to the guidelines within. Before participating in Docusaurus' communities, [please read our Code of Conduct](https://engineering.fb.com/codeofconduct/). We have adopted the [Contributor Covenant](https://www.contributor-covenant.org/) and we expect that all community members adhere to the guidelines within.
## Stack Overflow ## Stack Overflow {#stack-overflow}
Stack Overflow is a popular forum to ask code-level questions or if you're stuck with a specific error. Read through the [existing questions](https://stackoverflow.com/questions/tagged/docusaurus) tagged with **docusaurus** or [ask your own](https://stackoverflow.com/questions/ask?tags=docusaurus)! Stack Overflow is a popular forum to ask code-level questions or if you're stuck with a specific error. Read through the [existing questions](https://stackoverflow.com/questions/tagged/docusaurus) tagged with **docusaurus** or [ask your own](https://stackoverflow.com/questions/ask?tags=docusaurus)!
## Discussion forums ## 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 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.
@ -23,10 +23,10 @@ There are many online forums which are a great place for discussion about best p
- [#docusaurus-2-dev](https://discord.gg/6g6ASPA) for contributing help - [#docusaurus-2-dev](https://discord.gg/6g6ASPA) for contributing help
- [Reddit's Docusaurus community](https://www.reddit.com/r/docusaurus/) - [Reddit's Docusaurus community](https://www.reddit.com/r/docusaurus/)
## Feature requests ## Feature requests {#feature-requests}
For new feature requests, you can create a post on our [Canny board](/feedback), 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 [Canny board](/feedback), 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!
## News ## News {#news}
For the latest news about Docusaurus, [follow **@docusaurus** on Twitter](https://twitter.com/docusaurus) and the [official Docusaurus blog](/blog) on this website. For the latest news about Docusaurus, [follow **@docusaurus** on Twitter](https://twitter.com/docusaurus) and the [official Docusaurus blog](/blog) on this website.

8
website/community/team.mdx
View file

@ -10,7 +10,7 @@ import {
StudentFellowsTeamRow, StudentFellowsTeamRow,
} from '@site/src/components/TeamProfileCards'; } from '@site/src/components/TeamProfileCards';
## Active Team ## Active Team {#active-team}
The Docusaurus team works on the core functionality, plugins for the classic theme, as well as the Docusaurus documentation website. The Docusaurus team works on the core functionality, plugins for the classic theme, as well as the Docusaurus documentation website.
@ -18,19 +18,19 @@ Current members of the Docusaurus team are listed in alphabetical order below.
<ActiveTeamRow /> <ActiveTeamRow />
## Honorary Alumni ## Honorary Alumni {#honorary-alumni}
Docusaurus would never be what it is today without the huge contributions from these folks who have moved on to bigger and greater things. Docusaurus would never be what it is today without the huge contributions from these folks who have moved on to bigger and greater things.
<HonoraryAlumniTeamRow /> <HonoraryAlumniTeamRow />
## Student Fellows ## Student Fellows {#student-fellows}
A handful of students have also worked on Docusaurus as part of their school term/internship and the [Major League Hacking Fellowship program](https://fellowship.mlh.io/), contributing amazing features such as plugin options validation, migration tooling, and a Bootstrap theme. A handful of students have also worked on Docusaurus as part of their school term/internship and the [Major League Hacking Fellowship program](https://fellowship.mlh.io/), contributing amazing features such as plugin options validation, migration tooling, and a Bootstrap theme.
<StudentFellowsTeamRow /> <StudentFellowsTeamRow />
## Acknowledgements ## Acknowledgements {#acknowledgements}
Docusaurus was originally created by Joel Marcey. Today, Docusaurus has a few hundred open source contributors. We’d like to recognize a few people who have made significant contributions to Docusaurus and its documentation in the past and have helped maintain them over the years: Docusaurus was originally created by Joel Marcey. Today, Docusaurus has a few hundred open source contributors. We’d like to recognize a few people who have made significant contributions to Docusaurus and its documentation in the past and have helped maintain them over the years:

54
website/docs/api/docusaurus.config.js.md
View file

@ -5,13 +5,13 @@ description: API reference for Docusaurus configuration file.
slug: /docusaurus.config.js slug: /docusaurus.config.js
--- ---
## Overview ## Overview {#overview}
`docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site. `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
## Required fields ## Required fields {#required-fields}
### `title` ### `title` {#title}
- Type: `string` - Type: `string`
@ -23,7 +23,7 @@ module.exports = {
}; };
``` ```
### `favicon` ### `favicon` {#favicon}
- Type: `string` - Type: `string`
@ -54,7 +54,7 @@ module.exports = {
}; };
``` ```
### `url` ### `url` {#url}
- Type: `string` - Type: `string`
@ -66,7 +66,7 @@ module.exports = {
}; };
``` ```
### `baseUrl` ### `baseUrl` {#baseurl}
- Type: `string` - Type: `string`
@ -78,9 +78,9 @@ module.exports = {
}; };
``` ```
## Optional fields ## Optional fields {#optional-fields}
### `i18n` ### `i18n` {#i18n}
- Type: `Object` - Type: `Object`
@ -110,7 +110,7 @@ module.exports = {
- `label`: the label to use for this locale - `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 Araric, Hebrew, etc.)
### `noIndex` ### `noIndex` {#noindex}
- Type: `boolean` - Type: `boolean`
@ -124,7 +124,7 @@ module.exports = {
}; };
``` ```
### `onBrokenLinks` ### `onBrokenLinks` {#onbrokenlinks}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
@ -138,7 +138,7 @@ The broken links detection is only available for a production build (`docusaurus
::: :::
### `onBrokenMarkdownLinks` ### `onBrokenMarkdownLinks` {#onbrokenmarkdownlinks}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
@ -146,7 +146,7 @@ The behavior of Docusaurus, when it detects any broken markdown link.
By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed. By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed.
### `onDuplicateRoutes` ### `onDuplicateRoutes` {#onduplicateroutes}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
@ -154,7 +154,7 @@ The behavior of Docusaurus when it detects any [duplicate routes](/guides/creati
By default, it displays a warning after you run `yarn start` or `yarn build`. By default, it displays a warning after you run `yarn start` or `yarn build`.
### `tagline` ### `tagline` {#tagline}
- Type: `string` - Type: `string`
@ -167,7 +167,7 @@ module.exports = {
}; };
``` ```
### `organizationName` ### `organizationName` {#organizationname}
- Type: `string` - Type: `string`
@ -180,7 +180,7 @@ module.exports = {
}; };
``` ```
### `projectName` ### `projectName` {#projectname}
- Type: `string` - Type: `string`
@ -192,7 +192,7 @@ module.exports = {
}; };
``` ```
### `githubHost` ### `githubHost` {#githubhost}
- Type: `string` - Type: `string`
@ -204,7 +204,7 @@ module.exports = {
}; };
``` ```
### `themeConfig` ### `themeConfig` {#themeconfig}
- Type: `Object` - Type: `Object`
@ -273,7 +273,7 @@ module.exports = {
}; };
``` ```
### `plugins` ### `plugins` {#plugins}
<!-- TODO: configuration for plugins --> <!-- TODO: configuration for plugins -->
@ -285,7 +285,7 @@ module.exports = {
}; };
``` ```
### `themes` ### `themes` {#themes}
<!-- TODO: configuration for plugins --> <!-- TODO: configuration for plugins -->
@ -297,7 +297,7 @@ module.exports = {
}; };
``` ```
### `presets` ### `presets` {#presets}
<!-- TODO: configuration for presets --> <!-- TODO: configuration for presets -->
@ -309,7 +309,7 @@ module.exports = {
}; };
``` ```
### `customFields` ### `customFields` {#customfields}
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`. Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`.
@ -330,7 +330,7 @@ Attempting to add unknown field in the config will lead to error in build time:
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
``` ```
### `scripts` ### `scripts` {#scripts}
An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`. An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`.
@ -355,7 +355,7 @@ module.exports = {
}; };
``` ```
### `clientModules` ### `clientModules` {#clientmodules}
An array of client modules to load globally on your site: An array of client modules to load globally on your site:
@ -372,7 +372,7 @@ module.exports = {
See also: [`getClientModules()`](lifecycle-apis.md#getclientmodules). See also: [`getClientModules()`](lifecycle-apis.md#getclientmodules).
### `ssrTemplate` ### `ssrTemplate` {#ssrtemplate}
An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview) that will be used to render your application. This can be used to set custom attributes on the `body` tags, additional `meta` tags, customize the `viewport`, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from `upstream`. An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview) that will be used to render your application. This can be used to set custom attributes on the `body` tags, additional `meta` tags, customize the `viewport`, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from `upstream`.
@ -416,7 +416,7 @@ module.exports = {
}; };
``` ```
### `stylesheets` ### `stylesheets` {#stylesheets}
An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`. An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`.
@ -438,7 +438,7 @@ module.exports = {
}; };
``` ```
### `titleDelimiter` ### `titleDelimiter` {#titledelimiter}
- Type: `string` - Type: `string`
@ -452,7 +452,7 @@ module.exports = {
}; };
``` ```
### `baseUrlIssueBanner` ### `baseUrlIssueBanner` {#baseurlissuebanner}
- Type: `boolean` - Type: `boolean`

4
website/docs/api/plugins/overview.md
View file

@ -7,7 +7,7 @@ slug: '/api/plugins'
We provide official Docusaurus plugins. We provide official Docusaurus plugins.
## Content plugins ## Content plugins {#content-plugins}
These plugins are responsible to load your site's content, and create pages for your theme to render. These plugins are responsible to load your site's content, and create pages for your theme to render.
@ -15,7 +15,7 @@ These plugins are responsible to load your site's content, and create pages for
- [@docusaurus/plugin-content-blog](./plugin-content-blog.md) - [@docusaurus/plugin-content-blog](./plugin-content-blog.md)
- [@docusaurus/plugin-content-pages](./plugin-content-pages.md) - [@docusaurus/plugin-content-pages](./plugin-content-pages.md)
## Behavior plugins ## Behavior plugins {#behavior-plugins}
These plugins will add a useful behavior to your Docusaurus site. These plugins will add a useful behavior to your Docusaurus site.

4
website/docs/api/plugins/plugin-client-redirects.md
View file

@ -22,13 +22,13 @@ Before using this plugin, you should look if your hosting provider doesn't offer
::: :::
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-client-redirects npm install --save @docusaurus/plugin-client-redirects
``` ```
## Configuration ## Configuration {#configuration}
Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`: Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`:

10
website/docs/api/plugins/plugin-content-blog.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-content-blog'
Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus. Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-content-blog npm install --save @docusaurus/plugin-content-blog
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
@ -118,18 +118,18 @@ module.exports = {
}; };
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-blog` - **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>` - **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>`
- **JSON files**: N/A - **JSON files**: N/A
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-blog` - **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-plugin-content-blog website/i18n/<locale>/docusaurus-plugin-content-blog

12
website/docs/api/plugins/plugin-content-docs.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-content-docs'
Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus. Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-content-docs npm install --save @docusaurus/plugin-content-docs
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
@ -148,7 +148,7 @@ module.exports = {
}; };
``` ```
## Markdown Frontmatter ## Markdown Frontmatter {#markdown-frontmatter}
Markdown documents can use the following markdown frontmatter metadata fields, enclosed by a line `---` on either side: Markdown documents can use the following markdown frontmatter metadata fields, enclosed by a line `---` on either side:
@ -183,18 +183,18 @@ slug: /myDoc
My Document Markdown content My Document Markdown content
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-docs` - **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>` - **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations) - **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-docs/<version>` - **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-docs/<version>`
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-plugin-content-docs website/i18n/<locale>/docusaurus-plugin-content-docs

10
website/docs/api/plugins/plugin-content-pages.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-content-pages'
The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality. The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-content-pages npm install --save @docusaurus/plugin-content-pages
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
@ -67,18 +67,18 @@ module.exports = {
}; };
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-pages` - **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-pages-<pluginId>` - **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-pages-<pluginId>`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations) - **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-pages` - **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-plugin-content-pages website/i18n/<locale>/docusaurus-plugin-content-pages

4
website/docs/api/plugins/plugin-debug.md
View file

@ -16,7 +16,7 @@ If you don't have any sensitive information, you can keep it on in production [l
::: :::
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-debug npm install --save @docusaurus/plugin-debug
@ -30,7 +30,7 @@ By default, it's enabled in dev, and disabled in prod, to avoid exposing potenti
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

4
website/docs/api/plugins/plugin-google-analytics.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-google-analytics'
The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website. The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-google-analytics npm install --save @docusaurus/plugin-google-analytics
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

4
website/docs/api/plugins/plugin-google-gtag.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-google-gtag'
The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics. The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-google-gtag npm install --save @docusaurus/plugin-google-gtag
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

8
website/docs/api/plugins/plugin-ideal-image.md
View file

@ -6,13 +6,13 @@ slug: '/api/plugins/@docusaurus/plugin-ideal-image'
Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**. Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-ideal-image npm install --save @docusaurus/plugin-ideal-image
``` ```
## Configuration ## Configuration {#configuration}
Modify your `docusaurus.config.js` Modify your `docusaurus.config.js`
@ -24,7 +24,7 @@ module.exports = {
} }
``` ```
## Usage ## Usage {#usage}
This plugin supports the PNG, GIF and JPG formats only. This plugin supports the PNG, GIF and JPG formats only.
@ -39,7 +39,7 @@ import thumbnail from './path/to/img.png';
<Image img={require('./path/to/img.png')} /> <Image img={require('./path/to/img.png')} />
``` ```
## Options ## Options {#options}
| Option | Type | Default | Description | | Option | Type | Default | Description |
| --- | --- | --- | --- | | --- | --- | --- | --- |

28
website/docs/api/plugins/plugin-pwa.md
View file

@ -6,13 +6,13 @@ slug: '/api/plugins/@docusaurus/plugin-pwa'
Docusaurus Plugin to add PWA support using [Workbox](https://developers.google.com/web/tools/workbox). This plugin generates a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers) in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support. Docusaurus Plugin to add PWA support using [Workbox](https://developers.google.com/web/tools/workbox). This plugin generates a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers) in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-pwa npm install --save @docusaurus/plugin-pwa
``` ```
## Configuration ## Configuration {#configuration}
Create a [PWA manifest](https://web.dev/add-manifest/) at `./static/manifest.json`. Create a [PWA manifest](https://web.dev/add-manifest/) at `./static/manifest.json`.
@ -53,7 +53,7 @@ module.exports = {
}; };
``` ```
## Progressive Web App ## Progressive Web App {#progressive-web-app}
Having a service worker installed is not enough to make your application a PWA. You'll need to at least include a [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and have the correct tags in `<head>` ([Options > pwaHead](#pwahead)). Having a service worker installed is not enough to make your application a PWA. You'll need to at least include a [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and have the correct tags in `<head>` ([Options > pwaHead](#pwahead)).
@ -61,7 +61,7 @@ After deployment, you can use [Lighthouse](https://developers.google.com/web/too
For a more exhaustive list of what it takes for your site to be a PWA, refer to the [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist) For a more exhaustive list of what it takes for your site to be a PWA, refer to the [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist)
## App installation support ## App installation support {#app-installation-support}
If your browser supports it, you should be able to install a Docusaurus site as an app. If your browser supports it, you should be able to install a Docusaurus site as an app.
@ -73,7 +73,7 @@ App installation requires the https protocol and a valid manifest.
::: :::
## Offline mode (precaching) ## Offline mode (precaching) {#offline-mode-precaching}
We enable users to browse a Docusaurus site offline, by using service-worker precaching. We enable users to browse a Docusaurus site offline, by using service-worker precaching.
@ -95,9 +95,9 @@ Offline mode / precaching requires downloading all the static assets of the site
::: :::
## Options ## Options {#options}
### `debug` ### `debug` {#debug}
- Type: `boolean` - Type: `boolean`
- Default: `false` - Default: `false`
@ -109,7 +109,7 @@ Turn debug mode on:
- Unoptimized SW file output - Unoptimized SW file output
- Source maps - Source maps
### `offlineModeActivationStrategies` ### `offlineModeActivationStrategies` {#offlinemodeactivationstrategies}
- Type: `Array<'appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always'>` - Type: `Array<'appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always'>`
- Default: `['appInstalled','queryString','standalone']` - Default: `['appInstalled','queryString','standalone']`
@ -139,7 +139,7 @@ The [`standalone` strategy](https://petelepage.com/blog/2019/07/is-my-pwa-instal
::: :::
### `injectManifestConfig` ### `injectManifestConfig` {#injectmanifestconfig}
[Workbox options](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.injectManifest) to pass to `workbox.injectManifest()`. This gives you control over which assets will be precached, and be available offline. [Workbox options](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.injectManifest) to pass to `workbox.injectManifest()`. This gives you control over which assets will be precached, and be available offline.
@ -170,7 +170,7 @@ module.exports = {
}; };
``` ```
### `reloadPopup` ### `reloadPopup` {#reloadpopup}
- Type: `string | false` - Type: `string | false`
- Default: `'@theme/PwaReloadPopup'` - Default: `'@theme/PwaReloadPopup'`
@ -191,7 +191,7 @@ The default theme includes an implementation for the reload popup and uses [Infi
![pwa_reload.gif](/img/pwa_reload.gif) ![pwa_reload.gif](/img/pwa_reload.gif)
### `pwaHead` ### `pwaHead` {#pwahead}
- Type: `Array<{ tagName: string } & Record<string,string>>` - Type: `Array<{ tagName: string } & Record<string,string>>`
- Default: `[]` - Default: `[]`
@ -258,7 +258,7 @@ module.exports = {
}; };
``` ```
### `swCustom` ### `swCustom` {#swcustom}
- Type: `string | undefined` - Type: `string | undefined`
- Default: `undefined` - Default: `undefined`
@ -291,7 +291,7 @@ export default function swCustom(params) {
The module should have a `default` function export, and receives some params. The module should have a `default` function export, and receives some params.
### `swRegister` ### `swRegister` {#swregister}
- Type: `string | false` - Type: `string | false`
- Default: `'docusaurus-plugin-pwa/src/registerSW.js'` - Default: `'docusaurus-plugin-pwa/src/registerSW.js'`
@ -300,7 +300,7 @@ Adds an entry before the Docusaurus app so that registration can happen before t
Passing `false` will disable registration entirely. Passing `false` will disable registration entirely.
## Manifest example ## Manifest example {#manifest-example}
The Docusaurus site manifest can serve as an inspiration: The Docusaurus site manifest can serve as an inspiration:

4
website/docs/api/plugins/plugin-sitemap.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-sitemap'
This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately. This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-sitemap npm install --save @docusaurus/plugin-sitemap
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

4
website/docs/api/themes/overview.md
View file

@ -7,7 +7,7 @@ slug: '/api/themes'
We provide official Docusaurus themes. We provide official Docusaurus themes.
## Main themes ## Main themes {#main-themes}
The main themes implement the user interface for the [docs](../plugins/plugin-content-docs.md), [blog](../plugins/plugin-content-blog.md) and [pages](../plugins/plugin-content-pages.md) plugins. The main themes implement the user interface for the [docs](../plugins/plugin-content-docs.md), [blog](../plugins/plugin-content-blog.md) and [pages](../plugins/plugin-content-pages.md) plugins.
@ -24,7 +24,7 @@ We are not there yet: only the classic theme is production ready.
::: :::
## Enhancement themes ## Enhancement themes {#enhancement-themes}
These themes will enhance the existing main themes with additional user-interface related features. These themes will enhance the existing main themes with additional user-interface related features.

54
website/docs/api/themes/theme-configuration.md
View file

@ -6,9 +6,9 @@ slug: '/api/themes/configuration'
This configuration applies to all [main themes](./overview.md). This configuration applies to all [main themes](./overview.md).
## Common ## Common {#common}
### Color mode - dark mode ### Color mode - dark mode {#color-mode---dark-mode}
The classic theme provides by default light and dark mode support, with a navbar switch for the user. The classic theme provides by default light and dark mode support, with a navbar switch for the user.
@ -66,7 +66,7 @@ If you only want to support one color mode, you likely want to ignore user syste
::: :::
### Meta image ### Meta image {#meta-image}
You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`. You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.
@ -82,7 +82,7 @@ module.exports = {
}; };
``` ```
### Metadatas ### Metadatas {#metadatas}
You can configure additional html metadatas (and override existing ones). You can configure additional html metadatas (and override existing ones).
@ -96,7 +96,7 @@ module.exports = {
}; };
``` ```
### Announcement bar ### Announcement bar {#announcement-bar}
Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar. Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar.
@ -117,18 +117,18 @@ module.exports = {
}; };
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>` - **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>`
- **Multi-instance path**: N/A - **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations) - **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `N/A - **Markdown files**: `N/A
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-theme-classic website/i18n/<locale>/docusaurus-theme-classic
@ -138,9 +138,9 @@ website/i18n/<locale>/docusaurus-theme-classic
└── footer.json └── footer.json
``` ```
## Hooks ## Hooks {#hooks}
### `useThemeContext` ### `useThemeContext` {#usethemecontext}
React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use. React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use.
@ -175,9 +175,9 @@ function ExamplePage() {
::: :::
## Navbar ## Navbar {#navbar}
### Navbar title & logo ### Navbar title & logo {#navbar-title--logo}
You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab. You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.
@ -202,7 +202,7 @@ module.exports = {
}; };
``` ```
### Navbar items ### Navbar items {#navbar-items}
You can add items to the navbar via `themeConfig.navbar.items`. You can add items to the navbar via `themeConfig.navbar.items`.
@ -250,7 +250,7 @@ React Router should automatically apply active link styling to links, but you ca
Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes. Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes.
### Navbar dropdown ### Navbar dropdown {#navbar-dropdown}
Navbar items can also be dropdown items by specifying the `items`, an inner array of navbar items. Navbar items can also be dropdown items by specifying the `items`, an inner array of navbar items.
@ -282,7 +282,7 @@ module.exports = {
}; };
``` ```
### Navbar doc link ### Navbar doc link {#navbar-doc-link}
If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided `docId`. It will get the class `navbar__link--active` as long as you browse a doc of the same sidebar. If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided `docId`. It will get the class `navbar__link--active` as long as you browse a doc of the same sidebar.
@ -309,7 +309,7 @@ module.exports = {
}; };
``` ```
### Navbar docs version dropdown ### Navbar docs version dropdown {#navbar-docs-version-dropdown}
If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions. If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.
@ -338,7 +338,7 @@ module.exports = {
}; };
``` ```
### Navbar docs version ### Navbar docs version {#navbar-docs-version}
If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version. If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version.
@ -364,7 +364,7 @@ module.exports = {
}; };
``` ```
### Navbar locale dropdown ### Navbar locale dropdown {#navbar-locale-dropdown}
If you use the [i18n feature](../../i18n/i18n-introduction.md), this special navbar item type will render a dropdown with all your site's available locales. If you use the [i18n feature](../../i18n/i18n-introduction.md), this special navbar item type will render a dropdown with all your site's available locales.
@ -395,7 +395,7 @@ module.exports = {
}; };
``` ```
### Navbar search ### Navbar search {#navbar-search}
If you use the [search](../../search.md), the search bar will be the rightmost element in the navbar. If you use the [search](../../search.md), the search bar will be the rightmost element in the navbar.
@ -416,7 +416,7 @@ module.exports = {
}; };
``` ```
### Auto-hide sticky navbar ### Auto-hide sticky navbar {#auto-hide-sticky-navbar}
You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up. You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.
@ -432,7 +432,7 @@ module.exports = {
}; };
``` ```
### Navbar style ### Navbar style {#navbar-style}
You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected. You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected.
@ -452,17 +452,17 @@ module.exports = {
<!-- <!--
## Footer ## Footer {#footer}
TODO. TODO.
--> -->
## CodeBlock ## CodeBlock {#codeblock}
Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks.
### Theme ### Theme {#theme}
By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so. By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.
@ -485,7 +485,7 @@ If you use the line highlighting Markdown syntax, you might need to specify a di
::: :::
### Default language ### Default language {#default-language}
You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.: You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.:
@ -501,7 +501,7 @@ module.exports = {
}; };
``` ```
## Footer ## Footer {#footer-1}
You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo. You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo.
@ -517,7 +517,7 @@ You can add logo and a copyright to the footer via `themeConfig.footer`. Logo ca
} }
``` ```
## Footer Links ## Footer Links {#footer-links}
You can add links to the navbar via `themeConfig.footer.links`: You can add links to the navbar via `themeConfig.footer.links`:

2
website/docs/api/themes/theme-live-codeblock.md
View file

@ -10,7 +10,7 @@ This theme provides a `@theme/CodeBlock` component that is powered by react-live
npm install --save @docusaurus/theme-live-codeblock npm install --save @docusaurus/theme-live-codeblock
``` ```
### Configuration ### Configuration {#configuration}
```jsx title="docusaurus.config.js" ```jsx title="docusaurus.config.js"
module.exports = { module.exports = {

16
website/docs/blog.md
View file

@ -3,7 +3,7 @@ id: blog
title: Blog title: Blog
--- ---
## Initial setup ## Initial setup {#initial-setup}
To setup your site's blog, start by creating a `blog` directory. To setup your site's blog, start by creating a `blog` directory.
@ -24,7 +24,7 @@ module.exports = {
}; };
``` ```
## Adding posts ## Adding posts {#adding-posts}
To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-my-blog-post-title.md`. The post date is extracted from the file name. To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-my-blog-post-title.md`. The post date is extracted from the file name.
@ -51,7 +51,7 @@ This is my first post on Docusaurus 2.
A whole bunch of exploration to follow. A whole bunch of exploration to follow.
``` ```
## Header options ## Header options {#header-options}
The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options. The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options.
@ -66,7 +66,7 @@ The only required field is `title`; however, we provide options to add author in
- `image`: Cover or thumbnail image that will be used when displaying the link to your post. - `image`: Cover or thumbnail image that will be used when displaying the link to your post.
- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`. - `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`.
## Summary truncation ## Summary truncation {#summary-truncation}
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: 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:
@ -87,7 +87,7 @@ Not this.
Or this. Or this.
``` ```
## Feed ## Feed {#feed}
You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`. You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`.
@ -136,9 +136,9 @@ and for Atom:
https://{your-domain}/blog/atom.xml https://{your-domain}/blog/atom.xml
``` ```
## Advanced topics ## Advanced topics {#advanced-topics}
### Blog-only mode ### Blog-only mode {#blog-only-mode}
You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.
@ -185,7 +185,7 @@ module.exports = {
}; };
``` ```
### Multiple blogs ### Multiple blogs {#multiple-blogs}
By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`. By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`.

30
website/docs/cli.md
View file

@ -24,21 +24,21 @@ Once your website is bootstrapped, the website source will contain the Docusauru
} }
``` ```
## Index ## Index {#index}
import TOCInline from "@theme/TOCInline" import TOCInline from "@theme/TOCInline"
<TOCInline toc={toc[1].children}/> <TOCInline toc={toc[1].children}/>
## Docusaurus CLI commands ## Docusaurus CLI commands {#docusaurus-cli-commands}
Below is a list of Docusaurus CLI commands and their usages: Below is a list of Docusaurus CLI commands and their usages:
### `docusaurus start [siteDir]` ### `docusaurus start [siteDir]` {#docusaurus-start-sitedir}
Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server). Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server).
#### Options #### Options {#options}
| Name | Default | Description | | Name | Default | Description |
| --- | --- | --- | | --- | --- | --- |
@ -55,7 +55,7 @@ Please note that some functionality (for example, anchor links) will not work in
::: :::
#### Enabling HTTPS` #### Enabling HTTPS` {#enabling-https}
There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example. There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example.
@ -71,11 +71,11 @@ HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
4. Open `https://localhost:3000/` 4. Open `https://localhost:3000/`
### `docusaurus build [siteDir]` ### `docusaurus build [siteDir]` {#docusaurus-build-sitedir}
Compiles your site for production. Compiles your site for production.
#### Options #### Options {#options-1}
| Name | Default | Description | | Name | Default | Description |
| --- | --- | --- | | --- | --- | --- |
@ -90,7 +90,7 @@ For advanced minification of CSS bundle, we use the [advanced cssnano preset](ht
::: :::
### `docusaurus swizzle [siteDir]` ### `docusaurus swizzle [siteDir]` {#docusaurus-swizzle-sitedir}
:::caution :::caution
@ -111,7 +111,7 @@ Running the command will copy the relevant theme files to your site folder. You
`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 {#options-2}
| Name | Description | | Name | Description |
| ------------------ | -------------------------------------- | | ------------------ | -------------------------------------- |
@ -139,11 +139,11 @@ TODO a separate section for swizzle tutorial.
To learn more about swizzling, check [here](#). To learn more about swizzling, check [here](#).
--> -->
### `docusaurus deploy [siteDir]` ### `docusaurus deploy [siteDir]` {#docusaurus-deploy-sitedir}
Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.mdx#deploying-to-github-pages) for more details. Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.mdx#deploying-to-github-pages) for more details.
#### Options #### Options {#options-3}
| Name | Default | Description | | Name | Default | Description |
| --- | --- | --- | | --- | --- | --- |
@ -151,7 +151,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the
| `--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 custom deploy script. |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
### `docusaurus serve [siteDir]` ### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
Serve your built website locally. Serve your built website locally.
@ -163,13 +163,13 @@ Serve your built website locally.
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
| `--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`. | | `--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`. |
### `docusaurus clear [siteDir]` ### `docusaurus clear [siteDir]` {#docusaurus-clear-sitedir}
Clear a Docusaurus site's generated assets, caches, build artifacts. Clear a Docusaurus site's generated assets, caches, build artifacts.
We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site. We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.
### `docusaurus write-translations [siteDir]` ### `docusaurus write-translations [siteDir]` {#docusaurus-write-translations-sitedir}
Write the JSON translation files that you will have to translate. Write the JSON translation files that you will have to translate.
@ -182,6 +182,6 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--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 to add a prefix to each translation message, to help you highlight untranslated strings |
### `docusaurus write-heading-ids [siteDir]` ### `docusaurus write-heading-ids [siteDir]` {#docusaurus-write-heading-ids-sitedir}
Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site. Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site.

14
website/docs/configuration.md
View file

@ -9,7 +9,7 @@ Docusaurus has a unique take on configurations. We encourage you to congregate i
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 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 `docusaurus.config.js`? {#what-goes-into-a-docusaurusconfigjs}
You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options. You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options.
@ -21,19 +21,19 @@ The high-level overview of Docusaurus configuration can be categorized into:
For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md). For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md).
### Site metadata ### 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 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.
### Deployment configurations ### Deployment configurations {#deployment-configurations}
Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command. Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command.
It is recommended to check the [deployment docs](deployment.mdx) for more information. It is recommended to check the [deployment docs](deployment.mdx) for more information.
### Theme, plugin, and preset configurations ### Theme, plugin, and preset configurations {#theme-plugin-and-preset-configurations}
List the [theme](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages: List the [theme](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages:
@ -102,7 +102,7 @@ module.exports = {
For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md). For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md).
### Custom configurations ### Custom configurations {#custom-configurations}
Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`. Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`.
@ -121,7 +121,7 @@ module.exports = {
}; };
``` ```
## Accessing configuration from components ## Accessing configuration from components {#accessing-configuration-from-components}
Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`. Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`.
@ -148,7 +148,7 @@ If you just want to use those fields on the client side, you could create your o
::: :::
## Customizing Babel Configuration ## 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 project root.

48
website/docs/contributing.md
View file

@ -10,11 +10,11 @@ The [Open Source Guides](https://opensource.guide/) website has a collection of
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Building Welcoming Communities](https://opensource.guide/building-community/) - [Building Welcoming Communities](https://opensource.guide/building-community/)
## [Code of Conduct](https://code.fb.com/codeofconduct) ## [Code of Conduct](https://code.fb.com/codeofconduct) {#code-of-conduct}
Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated. Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
## Get involved ## Get involved {#get-involved}
There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started: There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started:
@ -25,24 +25,24 @@ There are many ways to contribute to Docusaurus, and many of them do not involve
Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help. Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help.
### Join our Discord channel ### Join our Discord channel {#join-our-discord-channel}
To participate in Docusaurus 2 dev, join the [#docusaurus-2-dev](https://discord.gg/Je6Ash6) channel. To participate in Docusaurus 2 dev, join the [#docusaurus-2-dev](https://discord.gg/Je6Ash6) channel.
## Our development process ## Our development process {#our-development-process}
Docusaurus uses [GitHub](https://github.com/facebook/docusaurus) as its source of truth. The core team will be working directly there. All changes will be public from the beginning. Docusaurus uses [GitHub](https://github.com/facebook/docusaurus) as its source of truth. The core team will be working directly there. All changes will be public from the beginning.
When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI. When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI.
### Reporting new issues ### Reporting new issues {#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 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. - **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. - **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.
### Reporting bugs ### Reporting bugs {#reporting-bugs}
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 a are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues). 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 a are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues).
@ -50,19 +50,19 @@ If you have questions about using Docusaurus, contact the Docusaurus Twitter acc
You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md/) You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md/)
### Reporting security bugs ### Reporting security bugs {#reporting-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. 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.
## Working on Docusaurus code ## Working on Docusaurus code {#working-on-docusaurus-code}
### Installation ### Installation {#installation}
1. Ensure you have [Yarn](https://yarnpkg.com/) installed 1. Ensure you have [Yarn](https://yarnpkg.com/) installed
2. After cloning the repository, run `yarn install` in the root of the repository 2. After cloning the repository, run `yarn install` in the root of the repository
3. To start a local development server serving the Docusaurus docs, go into the `website` directory and run `yarn start` 3. To start a local development server serving the Docusaurus docs, go into the `website` directory and run `yarn start`
### Semantic commit messages ### Semantic commit messages {#semantic-commit-messages}
See how a minor change to your commit message style can make you a better programmer. See how a minor change to your commit message style can make you a better programmer.
@ -93,26 +93,26 @@ The various types of commits:
Use lower case not title case! Use lower case not title case!
### Code conventions ### Code conventions {#code-conventions}
#### Style guide #### Style guide {#style-guide}
[Prettier](https://prettier.io/) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`. [Prettier](https://prettier.io/) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`.
However, there are still some styles that Prettier cannot pick up. However, there are still some styles that Prettier cannot pick up.
#### General #### General {#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.
- "Attractive" - "Attractive"
#### Documentation #### Documentation {#documentation}
- Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation. - Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation.
## Pull requests ## Pull requests {#pull-requests}
### Your first pull request ### Your first pull request {#your-first-pull-request}
So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at. So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.
@ -122,7 +122,7 @@ Working on your first Pull Request? You can learn how from this free video serie
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.
### Proposing a change ### Proposing a change {#proposing-a-change}
If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md/). If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md/).
@ -130,7 +130,7 @@ If you intend to change the public API (e.g., something in `docusaurus.config.js
If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue. If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
### Sending a pull request ### Sending a pull request {#sending-a-pull-request}
Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this [commit message style](#semantic-commit-messages). Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this [commit message style](#semantic-commit-messages).
@ -145,13 +145,13 @@ Please make sure the following is done when submitting a pull request:
All pull requests should be opened against the `master` branch. All pull requests should be opened against the `master` branch.
#### Test plan #### Test plan {#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, 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.
#### Breaking changes #### Breaking changes {#breaking-changes}
When adding a new breaking change, follow this template in your pull request: When adding a new breaking change, follow this template in your pull request:
@ -164,7 +164,7 @@ When adding a new breaking change, follow this template in your pull request:
- **Severity (number of people affected x effort)**: - **Severity (number of people affected x effort)**:
``` ```
#### Copyright header for source code #### Copyright header for source code {#copyright-header-for-source-code}
Copy and paste this to the top of your new file(s): Copy and paste this to the top of your new file(s):
@ -177,14 +177,14 @@ Copy and paste this to the top of your new file(s):
*/ */
``` ```
#### Contributor License Agreement (CLA) #### Contributor License Agreement (CLA) {#contributor-license-agreement-cla}
In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla). In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
### What happens next? ### What happens next? {#what-happens-next}
The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above. The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
## License ## License {#license}
By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license. By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license.

34
website/docs/deployment.mdx
View file

@ -13,7 +13,7 @@ Once it finishes, the static files will be generated within the `build/` directo
You can deploy your site to static site hosting services such as [Vercel](https://vercel.com/), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/docs/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too! You can deploy your site to static site hosting services such as [Vercel](https://vercel.com/), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/docs/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too!
## Testing Build Local ## Testing Build Local {#testing-build-local}
It is important to test build before deploying to a production. Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve) command to test build locally. It is important to test build before deploying to a production. Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve) command to test build locally.
@ -21,7 +21,7 @@ It is important to test build before deploying to a production. Docusaurus inclu
npm run serve npm run serve
``` ```
## Self Hosting ## Self Hosting {#self-hosting}
:::warning :::warning
@ -35,11 +35,11 @@ Docusaurus can be self hosted using [`docusaurus serve`](cli.md#docusaurus-serve
npm run serve -- --build --port 80 --host 0.0.0.0 npm run serve -- --build --port 80 --host 0.0.0.0
``` ```
## Deploying to GitHub Pages ## Deploying to GitHub Pages {#deploying-to-github-pages}
Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository. Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository.
### `docusaurus.config.js` settings ### `docusaurus.config.js` settings {#docusaurusconfigjs-settings}
First, modify your `docusaurus.config.js` and add the required params: First, modify your `docusaurus.config.js` and add the required params:
@ -77,7 +77,7 @@ By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.
::: :::
### Environment settings ### Environment settings {#environment-settings}
Specify the Git user as an environment variable. Specify the Git user as an environment variable.
@ -100,7 +100,7 @@ GitHub enterprise installations should work in the same manner as github.com; yo
| ------------- | ----------------------------------------------- | | ------------- | ----------------------------------------------- |
| `GITHUB_HOST` | The domain name of your GitHub enterprise site. | | `GITHUB_HOST` | The domain name of your GitHub enterprise site. |
### Deploy ### Deploy {#deploy}
Finally, to deploy your site to GitHub Pages, run: Finally, to deploy your site to GitHub Pages, run:
@ -136,7 +136,7 @@ cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
</Tabs> </Tabs>
```` ````
### Triggering deployment with GitHub Actions ### Triggering deployment with GitHub Actions {#triggering-deployment-with-github-actions}
[GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository. [GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
@ -209,7 +209,7 @@ jobs:
1. When pull request is merged to `documentation` branch or someone pushes to `documentation` branch directly it will be built and deployed to `gh-pages` branch. 1. When pull request is merged to `documentation` branch or someone pushes to `documentation` branch directly it will be built and deployed to `gh-pages` branch.
1. After this step, your updated documentation will be available on the GitHub pages. 1. After this step, your updated documentation will be available on the GitHub pages.
### Triggering deployment with Travis CI ### Triggering deployment with Travis CI {#triggering-deployment-with-travis-ci}
Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider. Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider.
@ -237,7 +237,7 @@ script:
Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script. Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
### Using Azure Pipelines ### Using Azure Pipelines {#using-azure-pipelines}
1. Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already. 1. Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already.
1. Create an organization and within the organization create a project and connect your repository from GitHub. 1. Create an organization and within the organization create a project and connect your repository from GitHub.
@ -273,7 +273,7 @@ steps:
displayName: 'yarn install and build' displayName: 'yarn install and build'
``` ```
### Using Drone ### Using Drone {#using-drone}
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. 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.
1. 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). 1. 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).
@ -307,7 +307,7 @@ trigger:
Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website. Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website.
## Deploying to Netlify ## Deploying to Netlify {#deploying-to-netlify}
To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured: To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
@ -336,7 +336,7 @@ Make sure to disable Netlify setting `Pretty URLs` to prevent lowercased URLs, u
::: :::
## Deploying to Vercel ## Deploying to Vercel {#deploying-to-vercel}
Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use. Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use.
@ -346,11 +346,11 @@ Import the project into Vercel using the [Import Flow](https://vercel.com/import
After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production). After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production).
## Deploying to Render ## 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 Surge ## Deploying to Surge {#deploying-to-surge}
Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL). Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL).
@ -378,7 +378,7 @@ First-time users of Surge would be prompted to create an account from the comman
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). 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).
### Using your domain ### Using your domain {#using-your-domain}
If you have a domain name you can deploy your site using surge to your domain using the command: If you have a domain name you can deploy your site using surge to your domain using the command:
@ -388,7 +388,7 @@ surge build/ yourdomain.com
Your site is now deployed for free at `subdomain.surge.sh` or `yourdomain.com` depending on the method you chose. Your site is now deployed for free at `subdomain.surge.sh` or `yourdomain.com` depending on the method you chose.
### Setting up CNAME file ### Setting up CNAME file {#setting-up-cname-file}
Store your domain in a CNAME file for future deployments with the following command: Store your domain in a CNAME file for future deployments with the following command:
@ -398,7 +398,7 @@ echo subdomain.surge.sh > CNAME
You can deploy any other changes in the future with the command `surge`. You can deploy any other changes in the future with the command `surge`.
## Deploying to QuantCDN ## Deploying to QuantCDN {#deploying-to-quantcdn}
1. Install [Quant CLI](https://docs.quantcdn.io/docs/cli/get-started) 1. Install [Quant CLI](https://docs.quantcdn.io/docs/cli/get-started)

2
website/docs/design-principles.md
View file

@ -15,7 +15,7 @@ This section is a work in progress.
- **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them. - **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. - **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.
## How Docusaurus works ## How Docusaurus works {#how-docusaurus-works}
<!-- moved in from how Docusaurus works @yangshun --> <!-- moved in from how Docusaurus works @yangshun -->

60
website/docs/docusaurus-core.md
View file

@ -6,9 +6,9 @@ sidebar_label: Client API
Docusaurus provides some APIs on the clients that can be helpful to you when building your site. Docusaurus provides some APIs on the clients that can be helpful to you when building your site.
## Components ## Components {#components}
### `<Head/>` ### `<Head/>` {#head}
This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around [React Helmet](https://github.com/nfl/react-helmet). This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around [React Helmet](https://github.com/nfl/react-helmet).
@ -54,7 +54,7 @@ Outputs:
</head> </head>
``` ```
### `<Link/>` ### `<Link/>` {#link}
This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an `IntersectionObserver` to fetch a low-priority request when the `<Link>` is in the viewport and then use an `onMouseOver` event to trigger a high-priority request when it is likely that a user will navigate to the requested resource. This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an `IntersectionObserver` to fetch a low-priority request when the `<Link>` is in the viewport and then use an `onMouseOver` event to trigger a high-priority request when it is likely that a user will navigate to the requested resource.
@ -77,7 +77,7 @@ const Page = () => (
); );
``` ```
#### `to`: string #### `to`: string {#to-string}
The target location to navigate to. Example: `/docs/introduction`. The target location to navigate to. Example: `/docs/introduction`.
@ -85,7 +85,7 @@ The target location to navigate to. Example: `/docs/introduction`.
<Link to="/courses" /> <Link to="/courses" />
``` ```
### `<Redirect/>` ### `<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.
@ -106,7 +106,7 @@ const Home = () => {
::: :::
### `<BrowserOnly/>` ### `<BrowserOnly/>` {#browseronly}
The `<BrowserOnly>` component accepts a `children` prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the `window`/`document` objects are being accessed). To improve SEO, you can also provide fallback content using the `fallback` prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser. The `<BrowserOnly>` component accepts a `children` prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the `window`/`document` objects are being accessed). To improve SEO, you can also provide fallback content using the `fallback` prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser.
@ -125,13 +125,13 @@ const MyComponent = () => {
}; };
``` ```
### `<Interpolate/>` ### `<Interpolate/>` {#interpolate}
A simple interpolation component for text containing dynamic placeholders. A simple interpolation component for text containing dynamic placeholders.
The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...). The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...).
#### Props #### Props {#props}
- `children`: text containing interpolation placeholders like `{placeholderName}` - `children`: text containing interpolation placeholders like `{placeholderName}`
- `values`: object containing interpolation placeholder values - `values`: object containing interpolation placeholder values
@ -160,7 +160,7 @@ export default function VisitMyWebsiteMessage() {
} }
``` ```
### `<Translate/>` ### `<Translate/>` {#translate}
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). 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).
@ -174,14 +174,14 @@ Apart the `values` prop used for interpolation, it is **not possible to use vari
::: :::
#### Props #### Props {#props-1}
- `children`: untranslated string in the default site locale (can contain [interpolation placeholders](#interpolate)) - `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 use as key in JSON translation files
- `description`: optional text to help the translator - `description`: optional text to help the translator
- `values`: optional object containing interpolation placeholder values - `values`: optional object containing interpolation placeholder values
#### Example #### Example {#example}
```jsx title="src/index.js" ```jsx title="src/index.js"
import React from 'react'; import React from 'react';
@ -215,9 +215,9 @@ export default function Home() {
} }
``` ```
## Hooks ## Hooks {#hooks}
### `useDocusaurusContext` ### `useDocusaurusContext` {#usedocusauruscontext}
React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md), and some additional site metadata. React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md), and some additional site metadata.
@ -258,7 +258,7 @@ const MyComponent = () => {
}; };
``` ```
### `useBaseUrl` ### `useBaseUrl` {#usebaseurl}
React hook to prepend your site `baseUrl` to a string. React hook to prepend your site `baseUrl` to a string.
@ -273,7 +273,7 @@ The `/baseUrl/` prefix is automatically added to all **absolute paths** by defau
::: :::
#### Options #### Options {#options}
```ts ```ts
type BaseUrlOptions = { type BaseUrlOptions = {
@ -282,7 +282,7 @@ type BaseUrlOptions = {
}; };
``` ```
#### Example usage: #### Example usage: {#example-usage}
```jsx ```jsx
import React from 'react'; import React from 'react';
@ -308,7 +308,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
::: :::
### `useBaseUrlUtils` ### `useBaseUrlUtils` {#usebaseurlutils}
Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url. Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
@ -328,7 +328,7 @@ const Component = () => {
}; };
``` ```
### `useGlobalData` ### `useGlobalData` {#useglobaldata}
React hook to access Docusaurus global data created by all the plugins. React hook to access Docusaurus global data created by all the plugins.
@ -369,7 +369,7 @@ Inspect your site's global data at `./docusaurus/globalData.json`
::: :::
### `usePluginData` ### `usePluginData` {#useplugindata}
Access global data created by a specific plugin instance. Access global data created by a specific plugin instance.
@ -393,7 +393,7 @@ const MyComponent = () => {
}; };
``` ```
### `useAllPluginInstancesData` ### `useAllPluginInstancesData` {#useallplugininstancesdata}
Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id. Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.
@ -414,13 +414,13 @@ const MyComponent = () => {
}; };
``` ```
## Functions ## Functions {#functions}
### `interpolate` ### `interpolate` {#interpolate-1}
The imperative counterpart of the [`<Interpolate>`](#interpolate) component. The imperative counterpart of the [`<Interpolate>`](#interpolate) component.
#### Signature #### Signature {#signature}
```ts ```ts
// Simple string interpolation // Simple string interpolation
@ -433,7 +433,7 @@ function interpolate(
): ReactNode; ): ReactNode;
``` ```
#### Example #### Example {#example-1}
```jsx ```jsx
// highlight-start // highlight-start
@ -443,7 +443,7 @@ import {interpolate} from '@docusaurus/Interpolate';
const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'}); const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});
``` ```
### `translate` ### `translate` {#translate-1}
The imperative counterpart of the [`<Translate>`](#translate) component. Also supporting [placeholders interpolation](#interpolate). The imperative counterpart of the [`<Translate>`](#translate) component. Also supporting [placeholders interpolation](#interpolate).
@ -457,7 +457,7 @@ Use the imperative API for the **rare cases** where a **component cannot be used
::: :::
#### Signature #### Signature {#signature-1}
```ts ```ts
function translate( function translate(
@ -466,7 +466,7 @@ function translate(
): string; ): string;
``` ```
#### Example #### Example {#example-2}
```jsx title="src/index.js" ```jsx title="src/index.js"
import React from 'react'; import React from 'react';
@ -504,9 +504,9 @@ export default function Home() {
} }
``` ```
## Modules ## Modules {#modules}
### `ExecutionEnvironment` ### `ExecutionEnvironment` {#executionenvironment}
A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code. A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code.
@ -527,7 +527,7 @@ const MyPage = () => {
| `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. | | `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. |
| `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. | | `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. |
### `constants` ### `constants` {#constants}
A module exposing useful constants to client-side theme code. A module exposing useful constants to client-side theme code.

10
website/docs/guides/creating-pages.md
View file

@ -10,7 +10,7 @@ The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
You can use React components, or Markdown. You can use React components, or Markdown.
## Add a React page ## Add a React page {#add-a-react-page}
Create a file `/src/pages/helloReact.js`: Create a file `/src/pages/helloReact.js`:
@ -50,7 +50,7 @@ You can also create TypeScript pages with the `.tsx` extension (`helloReact.tsx`
::: :::
## Add a Markdown page ## Add a Markdown page {#add-a-markdown-page}
Create a file `/src/pages/helloMarkdown.md`: Create a file `/src/pages/helloMarkdown.md`:
@ -78,7 +78,7 @@ You can use the full power of React in Markdown pages too, refer to the [MDX](ht
::: :::
## Routing ## Routing {#routing}
If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example: If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:
@ -113,10 +113,10 @@ All JavaScript/TypeScript files within the `src/pages/` directory will have corr
::: :::
## Using React ## 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. 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}
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. 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.

6
website/docs/guides/docs/docs-introduction.md
View file

@ -7,7 +7,7 @@ slug: /docs-introduction
The docs feature provides users with a way to organize Markdown files in a hierarchical format. The docs feature provides users with a way to organize Markdown files in a hierarchical format.
## Document ID ## Document ID {#document-id}
Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
@ -49,7 +49,7 @@ It is possible to use:
::: :::
## Home page docs ## Home page docs {#home-page-docs}
If you want a document to be available at the root, and have a path like `https://v2.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://v2.docusaurus.io/docs/`, you can use the slug frontmatter:
@ -61,7 +61,7 @@ slug: /
Lorem ipsum Lorem ipsum
``` ```
## Docs-only mode ## Docs-only mode {#docs-only-mode}
If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead. If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.

4
website/docs/guides/docs/docs-markdown-features.mdx
View file

@ -7,11 +7,11 @@ 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-frontmatter}
Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter) Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
## Referencing other documents ## Referencing other documents {#referencing-other-documents}
If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`). If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).

14
website/docs/guides/docs/docs-multi-instance.mdx
View file

@ -13,13 +13,13 @@ This feature is only useful for [versioned documentations](./versioning.md). It
::: :::
## Use-cases ## Use-cases {#use-cases}
Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more). Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more).
These documentations may even have different versioning/release lifecycles. These documentations may even have different versioning/release lifecycles.
### Mobile SDKs documentation ### Mobile SDKs documentation {#mobile-sdks-documentation}
If you build a cross-platform mobile SDK, you may have 2 documentations: If you build a cross-platform mobile SDK, you may have 2 documentations:
@ -36,7 +36,7 @@ If someone edits the iOS documentation, is it really useful to rebuild everythin
::: :::
### Versioned and unversioned doc ### Versioned and unversioned doc {#versioned-and-unversioned-doc}
Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them. Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them.
@ -45,7 +45,7 @@ We use this pattern on the Docusaurus website itself:
- The [/docs/\*](/docs) section is versioned - The [/docs/\*](/docs) section is versioned
- The [/community/\*](/community/support) section is unversioned - The [/community/\*](/community/support) section is unversioned
## Setup ## Setup {#setup}
Let's consider we 2 documentations: Let's consider we 2 documentations:
@ -138,7 +138,7 @@ We consider that the `product` instance is the most important one, and make it t
::: :::
## Versioned paths ## Versioned paths {#versioned-paths}
Each instance will store versioned docs in a distinct folder. Each instance will store versioned docs in a distinct folder.
@ -162,7 +162,7 @@ The instance paths will be simpler, and retro-compatible with a single-instance
::: :::
## Tagging new versions ## Tagging new versions {#tagging-new-versions}
Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run: Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run:
@ -182,7 +182,7 @@ To version the non-default/community docs plugin instance:
npm run docusaurus docs:version:community 1.0.0 npm run docusaurus docs:version:community 1.0.0
``` ```
## Docs navbar items ## Docs navbar items {#docs-navbar-items}
Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute. Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute.

22
website/docs/guides/docs/sidebar.md
View file

@ -27,7 +27,7 @@ module.exports = {
}; };
``` ```
## Sidebar object ## Sidebar object {#sidebar-object}
A sidebar object contains [sidebar items](#understanding-sidebar-items) and it is defined like this: A sidebar object contains [sidebar items](#understanding-sidebar-items) and it is defined like this:
@ -83,7 +83,7 @@ Shorthand notation relies on the iteration order of JavaScript object keys for t
::: :::
## Using multiple sidebars ## Using multiple sidebars {#using-multiple-sidebars}
You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object. You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.
@ -107,7 +107,7 @@ For example, with the above example, when displaying the `doc2` page, the sideba
For more information about sidebars and how they relate to doc pages, see [Navbar doc link](../../api/themes/theme-configuration.md#navbar-doc-link). For more information about sidebars and how they relate to doc pages, see [Navbar doc link](../../api/themes/theme-configuration.md#navbar-doc-link).
## Understanding sidebar items ## Understanding sidebar items {#understanding-sidebar-items}
As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarItem as a `type` that defines what the item links to. As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarItem as a `type` that defines what the item links to.
@ -118,7 +118,7 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarIte
- [Ref](#creating-a-link-to-page-without-sidebar) - [Ref](#creating-a-link-to-page-without-sidebar)
- [Category](#creating-a-hierarchy) - [Category](#creating-a-hierarchy)
### Linking to a doc page ### Linking to a doc page {#linking-to-a-doc-page}
Set `type` to `doc` to link to a documentation page. This is the default type. Set `type` to `doc` to link to a documentation page. This is the default type.
@ -163,7 +163,7 @@ module.exports = {
}; };
``` ```
### Creating a generic link ### Creating a generic link {#creating-a-generic-link}
Set `type` to `link` to link to a non-documentation page. For example, to create an external link. Set `type` to `link` to link to a non-documentation page. For example, to create an external link.
@ -185,7 +185,7 @@ Example:
} }
``` ```
### Creating a link to page without sidebar ### Creating a link to page without sidebar {#creating-a-link-to-page-without-sidebar}
Set `type` to `ref` to link to a documentation page without binding it to a sidebar. This means the sidebar disappears when the user displays the linked page. Set `type` to `ref` to link to a documentation page without binding it to a sidebar. This means the sidebar disappears when the user displays the linked page.
@ -205,7 +205,7 @@ Example:
} }
``` ```
### Creating a hierarchy ### Creating a hierarchy {#creating-a-hierarchy}
The Sidebar item type that creates a hierarchy in the sidebar. Set `type` to `category`. The Sidebar item type that creates a hierarchy in the sidebar. Set `type` to `category`.
@ -260,7 +260,7 @@ module.exports = {
}; };
``` ```
#### Collapsible categories #### Collapsible categories {#collapsible-categories}
For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`: For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`:
@ -274,7 +274,7 @@ module.exports = {
}; };
``` ```
#### Expanded categories by default #### Expanded categories by default {#expanded-categories-by-default}
For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`: For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`:
@ -294,7 +294,7 @@ module.exports = {
}; };
``` ```
## Hideable sidebar ## Hideable sidebar {#hideable-sidebar}
Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets). Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
@ -308,7 +308,7 @@ module.exports = {
}; };
``` ```
## Passing custom props ## Passing custom props {#passing-custom-props}
To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items: To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:

28
website/docs/guides/docs/versioning.md
View file

@ -16,7 +16,7 @@ Most of the time, you don't need versioning as it will just increase your build
To better understand how versioning works and see if it suits your needs, you can read on below. To better understand how versioning works and see if it suits your needs, you can read on below.
## Directory structure ## Directory structure {#directory-structure}
```shell ```shell
website website
@ -50,7 +50,7 @@ The table below explains how a versioned file maps to its version and the genera
| `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello | | `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello |
| `docs/hello.md` | next | /docs/next/hello | | `docs/hello.md` | next | /docs/next/hello |
### Tagging a new version ### Tagging a new version {#tagging-a-new-version}
1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master. 1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master.
1. Enter a new version number. 1. Enter a new version number.
@ -65,9 +65,9 @@ When tagging a new version, the document versioning mechanism will:
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`. - Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number to `versions.json`. - Append the new version number to `versions.json`.
## Docs ## Docs {#docs}
### Creating new docs ### Creating new docs {#creating-new-docs}
1. Place the new file into the corresponding version folder. 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. 1. Include the reference for the new file into the corresponding sidebar file, according to version number.
@ -92,7 +92,7 @@ versioned_docs/version-1.0.0/new.md
versioned_sidebars/version-1.0.0-sidebars.json versioned_sidebars/version-1.0.0-sidebars.json
``` ```
### Linking docs ### Linking docs {#linking-docs}
- Remember to include the `.md` extension. - Remember to include the `.md` extension.
- Files will be linked to correct corresponding version. - Files will be linked to correct corresponding version.
@ -104,11 +104,11 @@ The [@hello](hello.md#paginate) document is great!
See the [Tutorial](../getting-started/tutorial.md) for more info. See the [Tutorial](../getting-started/tutorial.md) for more info.
``` ```
## Versions ## Versions {#versions}
Each directory in `versioned_docs/` will represent a documentation version. Each directory in `versioned_docs/` will represent a documentation version.
### Updating an existing version ### Updating an existing version {#updating-an-existing-version}
You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published. You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published.
@ -118,7 +118,7 @@ You can update multiple docs versions at the same time because each directory in
Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`. Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
### Deleting an existing version ### Deleting an existing version {#deleting-an-existing-version}
You can delete/remove versions as well. You can delete/remove versions as well.
@ -137,9 +137,9 @@ Example:
2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`. 2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`.
3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`. 3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`.
## Recommended practices ## Recommended practices {#recommended-practices}
### Figure out the behavior for the "current" version ### Figure out the behavior for the "current" version {#figure-out-the-behavior-for-the-current-version}
The "current" version is the version name for the `./docs` folder. The "current" version is the version name for the `./docs` folder.
@ -168,17 +168,17 @@ The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, an
See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details. See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details.
### Version your documentation only when needed ### Version your documentation only when needed {#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 a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.
Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files. 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 {#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 version 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. **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 version with the lowest being `22.X`. Keep it small 😊
### Use absolute import within the docs ### 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:
@ -187,7 +187,7 @@ Don't use relative paths import within the docs. Because when we cut a version t
+ import Foo from '@site/src/components/Foo'; + import Foo from '@site/src/components/Foo';
``` ```
### Global or versioned colocated assets ### 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

2
website/docs/guides/markdown-features/markdown-features-admonitions.mdx
View file

@ -69,7 +69,7 @@ Danger danger, mayday!
::: :::
## Specifying title ## Specifying title {#specifying-title}
You may also specify an optional title You may also specify an optional title

8
website/docs/guides/markdown-features/markdown-features-assets.mdx
View file

@ -20,7 +20,7 @@ Let's imagine the following file structure:
/website/docs/assets/docusaurus-asset-example-pdf.pdf /website/docs/assets/docusaurus-asset-example-pdf.pdf
``` ```
## Images ## Images {#images}
You can use images in Markdown, or by requiring them and using a JSX image tag: You can use images in Markdown, or by requiring them and using a JSX image tag:
@ -57,7 +57,7 @@ If you are using [@docusaurus/plugin-ideal-image](../../using-plugins.md#docusau
::: :::
## Files ## 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.
@ -83,7 +83,7 @@ or
[Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf) [Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf)
## Inline SVGs ## Inline SVGs {#inline-svgs}
Docusaurus supports inlining SVGs out of the box. Docusaurus supports inlining SVGs out of the box.
@ -117,7 +117,7 @@ html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
<DocusaurusSvg className="themedDocusaurus" /> <DocusaurusSvg className="themedDocusaurus" />
## Themed Images ## Themed Images {#themed-images}
Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme. Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme.

12
website/docs/guides/markdown-features/markdown-features-code-blocks.mdx
View file

@ -7,7 +7,7 @@ slug: /markdown-features/code-blocks
Code blocks within documentation are super-powered 💪. Code blocks within documentation are super-powered 💪.
## Code title ## 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 `title` key after the language (leave a space between them).
@ -23,7 +23,7 @@ function HelloCodeTitle(props) {
} }
``` ```
## Syntax highlighting ## 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 specifications of MDX.
@ -95,7 +95,7 @@ const prismIncludeLanguages = (Prism) => {
You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions. You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions.
## Line highlighting ## Line highlighting {#line-highlighting}
You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language). You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
@ -220,7 +220,7 @@ Supported commenting syntax:
If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome. If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
## Interactive code editor ## Interactive code editor {#interactive-code-editor}
(Powered by [React Live](https://github.com/FormidableLabs/react-live)) (Powered by [React Live](https://github.com/FormidableLabs/react-live))
@ -292,7 +292,7 @@ function Clock(props) {
} }
``` ```
### Imports ### Imports {#imports}
:::caution react-live and imports :::caution react-live and imports
@ -345,7 +345,7 @@ function MyPlayground(props) {
} }
``` ```
## Multi-language support code blocks ## 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 switching between them using a tabs component.

8
website/docs/guides/markdown-features/markdown-features-headings.mdx
View file

@ -5,7 +5,7 @@ description: Using Markdown headings
slug: /markdown-features/headings slug: /markdown-features/headings
--- ---
## Markdown headings ## Markdown headings {#markdown-headings}
You can use regular Markdown headings. You can use regular Markdown headings.
@ -19,7 +19,7 @@ You can use regular Markdown headings.
Markdown headings appear as a table-of-contents entry. Markdown headings appear as a table-of-contents entry.
## Heading ids ## 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.
@ -33,7 +33,7 @@ Heading ids allow you to link to a specific document heading in Markdown or JSX:
<Link to="#heading-id">link</Link> <Link to="#heading-id">link</Link>
``` ```
### Generated ids ### Generated ids {#generated-ids}
By default, Docusaurus will generate heading ids for you, based on the heading text. By default, Docusaurus will generate heading ids for you, based on the heading text.
@ -44,7 +44,7 @@ Generated ids have **some limits**:
- The id might not look good - The id might not look good
- You might want to **change or translate** the text without updating the existing id - You might want to **change or translate** the text without updating the existing id
### Explicit ids ### Explicit ids {#explicit-ids}
A special Markdown syntax lets you set an **explicit heading id**: A special Markdown syntax lets you set an **explicit heading id**:

28
website/docs/guides/markdown-features/markdown-features-inline-toc.mdx
View file

@ -11,7 +11,7 @@ Each markdown document displays a tab of content on the top-right corner.
But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX. But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
## Full table of contents ## Full table of contents {#full-table-of-contents}
The `toc` variable is available in any MDX document, and contain all the top level headings of a MDX document. The `toc` variable is available in any MDX document, and contain all the top level headings of a MDX document.
@ -31,7 +31,7 @@ import TOCInline from '@theme/TOCInline';
</BrowserWindow> </BrowserWindow>
``` ```
## Custom table of contents ## Custom table of contents {#custom-table-of-contents}
The `toc` props is just a list of table of contents items: The `toc` props is just a list of table of contents items:
@ -72,50 +72,50 @@ The underlying content is just an example to have more table-of-contents items a
::: :::
## Example Section 1 ## Example Section 1 {#example-section-1}
Lorem ipsum Lorem ipsum
### Example Subsection 1 a ### Example Subsection 1 a {#example-subsection-1-a}
Lorem ipsum Lorem ipsum
### Example Subsection 1 b ### Example Subsection 1 b {#example-subsection-1-b}
Lorem ipsum Lorem ipsum
### Example Subsection 1 c ### Example Subsection 1 c {#example-subsection-1-c}
Lorem ipsum Lorem ipsum
## Example Section 2 ## Example Section 2 {#example-section-2}
Lorem ipsum Lorem ipsum
### Example Subsection 2 a ### Example Subsection 2 a {#example-subsection-2-a}
Lorem ipsum Lorem ipsum
### Example Subsection 2 b ### Example Subsection 2 b {#example-subsection-2-b}
Lorem ipsum Lorem ipsum
### Example Subsection 2 c ### Example Subsection 2 c {#example-subsection-2-c}
Lorem ipsum Lorem ipsum
## Example Section 3 ## Example Section 3 {#example-section-3}
Lorem ipsum Lorem ipsum
### Example Subsection 3 a ### Example Subsection 3 a {#example-subsection-3-a}
Lorem ipsum Lorem ipsum
### Example Subsection 3 b ### Example Subsection 3 b {#example-subsection-3-b}
Lorem ipsum Lorem ipsum
### Example Subsection 3 c ### Example Subsection 3 c {#example-subsection-3-c}
Lorem ipsum Lorem ipsum

4
website/docs/guides/markdown-features/markdown-features-plugins.mdx
View file

@ -9,7 +9,7 @@ You can expand the MDX functionalities, using plugins.
Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX. Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
## Configuring plugins ## Configuring plugins {#configuring-plugins}
An MDX plugin is usually a npm package, so you install them like other npm packages using npm. An MDX plugin is usually a npm package, so you install them like other npm packages using npm.
@ -50,7 +50,7 @@ module.exports = {
}; };
``` ```
## Configuring plugin options ## Configuring plugin options {#configuring-plugin-options}
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so: Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so:

4
website/docs/guides/markdown-features/markdown-features-tabs.mdx
View file

@ -50,7 +50,7 @@ By default, tabs are rendered eagerly, but it is possible to load them lazily by
::: :::
## Syncing tab choices ## 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 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.
@ -190,7 +190,7 @@ Tab choices with different `groupId`s will not interfere with each other:
</Tabs> </Tabs>
``` ```
## Customizing tabs ## 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 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:

46
website/docs/i18n/i18n-crowdin.mdx
View file

@ -25,7 +25,7 @@ Use this **[community-driven GitHub issue](https://github.com/facebook/docusauru
::: :::
## Crowdin overview ## Crowdin overview {#crowdin-overview}
Crowdin is a translation SaaS, offering a [free plan for open-source projects](https://crowdin.com/page/open-source-project-setup-request). Crowdin is a translation SaaS, offering a [free plan for open-source projects](https://crowdin.com/page/open-source-project-setup-request).
@ -41,13 +41,13 @@ The [`crowdin.yml` configuration file](https://support.crowdin.com/configuration
Read the **[official documentation](https://support.crowdin.com/)** to know more about advanced features and different translation workflows. Read the **[official documentation](https://support.crowdin.com/)** to know more about advanced features and different translation workflows.
## Crowdin tutorial ## Crowdin tutorial {#crowdin-tutorial}
This is a walk-through of using Crowdin to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md). This is a walk-through of using Crowdin to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
The end result can be seen at [docusaurus-crowdin-example.netlify.app](https://docusaurus-crowdin-example.netlify.app/) ([repository](https://github.com/slorber/docusaurus-crowdin-example)). The end result can be seen at [docusaurus-crowdin-example.netlify.app](https://docusaurus-crowdin-example.netlify.app/) ([repository](https://github.com/slorber/docusaurus-crowdin-example)).
### Prepare the Docusaurus site ### Prepare the Docusaurus site {#prepare-the-docusaurus-site}
Initialize a new Docusaurus site: Initialize a new Docusaurus site:
@ -99,7 +99,7 @@ export default function Home() {
} }
``` ```
### Create a Crowdin project ### Create a Crowdin project {#create-a-crowdin-project}
Sign up on [Crowdin](https://crowdin.com/), and create a project. Sign up on [Crowdin](https://crowdin.com/), and create a project.
@ -109,7 +109,7 @@ Use English as source language, and French as target language.
Your project is created, but it is empty for now. We will upload the files to translate in the next steps. Your project is created, but it is empty for now. We will upload the files to translate in the next steps.
### Create the Crowdin configuration ### Create the Crowdin configuration {#create-the-crowdin-configuration}
This configuration ([doc](https://support.crowdin.com/configuration-file/)) provides a mapping for the Crowdin CLI to understand: This configuration ([doc](https://support.crowdin.com/configuration-file/)) provides a mapping for the Crowdin CLI to understand:
@ -160,7 +160,7 @@ We advise to:
::: :::
#### Access token #### Access token {#access-token}
The `api_token_env` attribute defines the **env variable name** read by the Crowdin CLI. The `api_token_env` attribute defines the **env variable name** read by the Crowdin CLI.
@ -180,12 +180,12 @@ You should **not commit** it, and it may be a good idea to create a dedicated **
::: :::
#### Other configuration fields #### Other configuration fields {#other-configuration-fields}
- `project_id`: can be hardcoded, and is found on `https://crowdin.com/project/<MY_PROJECT_NAME>/settings#api` - `project_id`: can be hardcoded, and is found on `https://crowdin.com/project/<MY_PROJECT_NAME>/settings#api`
- `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything - `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything
### Install the Crowdin CLI ### 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 use the CLI in version `3.5.2`, but we expect `3.x` releases to keep working.
@ -219,7 +219,7 @@ Temporarily, you can hardcode your personal token in `crowdin.yml` with `api_tok
::: :::
### Upload the sources ### Upload the sources {#upload-the-sources}
Generate the JSON translation files for the default language in `website/i18n/en`: Generate the JSON translation files for the default language in `website/i18n/en`:
@ -239,7 +239,7 @@ Your source files are now visible on the Crowdin interface: `https://crowdin.com
![Crowdin UI showing Docusaurus source files](/img/crowdin/crowdin-source-files.png) ![Crowdin UI showing Docusaurus source files](/img/crowdin/crowdin-source-files.png)
### Translate the sources ### Translate the sources {#translate-the-sources}
On `https://crowdin.com/project/<MY_PROJECT_NAME>`, click on the French target language. On `https://crowdin.com/project/<MY_PROJECT_NAME>`, click on the French target language.
@ -278,7 +278,7 @@ Use the `Hide String` feature first, as Crowdin is pre-translating things too op
::: :::
### Download the translations ### Download the translations {#download-the-translations}
Use the Crowdin CLI to download the translated JSON and Markdown files. Use the Crowdin CLI to download the translated JSON and Markdown files.
@ -296,7 +296,7 @@ npm run start -- --locale fr
Make sure that your website is now translated in French at `http://localhost:3000/fr/`. Make sure that your website is now translated in French at `http://localhost:3000/fr/`.
### Automate with CI ### 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.
@ -328,9 +328,9 @@ Crowdin does not support well multiple concurrent uploads/downloads: it is prefe
::: :::
## Advanced Crowdin topics ## Advanced Crowdin topics {#advanced-crowdin-topics}
### MDX ### MDX {#mdx}
:::caution :::caution
@ -340,7 +340,7 @@ Pay special attention to the JSX fragments in MDX documents!
Crowdin **does not support officially MDX**, but they added **support for the `.mdx` extension**, and interpret such files as Markdown (instead of plain text). Crowdin **does not support officially MDX**, but they added **support for the `.mdx` extension**, and interpret such files as Markdown (instead of plain text).
#### MDX problems #### 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 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.
@ -348,7 +348,7 @@ Simple JSX fragments using simple string props like `<Username name="Sebastien"/
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. 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 {#mdx-solutions}
We recommend moving the complex embedded JSX code as separate standalone components. We recommend moving the complex embedded JSX code as separate standalone components.
@ -394,7 +394,7 @@ This will:
- be interpreted by Docusaurus as regular JSX (as if it was not wrapped by any code block) - be interpreted by Docusaurus as regular JSX (as if it was not wrapped by any code block)
- unfortunately opt-out of MDX tooling (IDE syntax highlighting, Prettier...) - unfortunately opt-out of MDX tooling (IDE syntax highlighting, Prettier...)
### Docs versioning ### Docs versioning {#docs-versioning}
Configure translation files for the `website/versioned_docs` folder. Configure translation files for the `website/versioned_docs` folder.
@ -412,7 +412,7 @@ Not using `Hide` leads to a much larger amount of `source strings` in quotas, an
::: :::
### Multi-instance plugins ### Multi-instance plugins {#multi-instance-plugins}
You need to configure translation files for each plugin instance. You need to configure translation files for each plugin instance.
@ -421,7 +421,7 @@ If you have a docs plugin instance with `id=ios`, you will need to configure tho
- `website/ios` - `website/ios`
- `website/ios_versioned_docs` (if versioned) - `website/ios_versioned_docs` (if versioned)
### Maintaining your site ### Maintaining your site {#maintaining-your-site}
Sometimes, you will **remove or rename a source file** on Git, and Crowdin will display CLI warnings: Sometimes, you will **remove or rename a source file** on Git, and Crowdin will display CLI warnings:
@ -431,7 +431,7 @@ When your sources are refactored, you should use the Crowdin UI to **update your
![Crowdin UI: renaming a file](/img/crowdin/crowdin-files-rename.png) ![Crowdin UI: renaming a file](/img/crowdin/crowdin-files-rename.png)
### VCS (Git) integrations ### VCS (Git) integrations {#vcs-git-integrations}
Crowdin has multiple VCS integrations for [GitHub](https://support.crowdin.com/github-integration/), GitLab, Bitbucket. Crowdin has multiple VCS integrations for [GitHub](https://support.crowdin.com/github-integration/), GitLab, Bitbucket.
@ -451,7 +451,7 @@ In practice, **it didn't work very reliably** for a few reasons:
- 2 users concurrently editing on Git and Crowdin can lead to a translation loss - 2 users concurrently editing on Git and Crowdin can lead to a translation loss
- It requires the `crowdin.yml` file to be at the root of the repository - It requires the `crowdin.yml` file to be at the root of the repository
### In-Context localization ### In-Context localization {#in-context-localization}
Crowdin has an [In-Context localization](https://support.crowdin.com/in-context-localization/) feature. Crowdin has an [In-Context localization](https://support.crowdin.com/in-context-localization/) feature.
@ -463,7 +463,7 @@ Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`,
::: :::
### 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`. 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`.
@ -511,7 +511,7 @@ It is currently **not possible to link to a specific file** in Crowdin.
::: :::
### Example configuration ### Example configuration {#example-configuration}
The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance: The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance:

20
website/docs/i18n/i18n-git.md
View file

@ -7,7 +7,7 @@ slug: /i18n/git
A **possible translation strategy** is to **version control the translation files** to Git (or any other [VCS](https://en.wikipedia.org/wiki/Version_control)). A **possible translation strategy** is to **version control the translation files** to Git (or any other [VCS](https://en.wikipedia.org/wiki/Version_control)).
## Tradeoffs ## Tradeoffs {#tradeoffs}
This strategy has advantages: This strategy has advantages:
@ -31,11 +31,11 @@ Refer to the [Docusaurus i18n RFC](https://github.com/facebook/docusaurus/issues
::: :::
## Git tutorial ## Git tutorial {#git-tutorial}
This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md). This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
### Prepare the Docusaurus site ### Prepare the Docusaurus site {#prepare-the-docusaurus-site}
Initialize a new Docusaurus site: Initialize a new Docusaurus site:
@ -87,7 +87,7 @@ export default function Home() {
} }
``` ```
### Initialize the `i18n` folder ### Initialize the `i18n` folder {#initialize-the-i18n-folder}
Use the [write-translations](../cli.md#docusaurus-write-translations) CLI command to initialize the JSON translation files for the French locale: Use the [write-translations](../cli.md#docusaurus-write-translations) CLI command to initialize the JSON translation files for the French locale:
@ -124,7 +124,7 @@ cp -r pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
Add all these files to Git. Add all these files to Git.
### Translate the files ### Translate the files {#translate-the-files}
Translate the Markdown and JSON files in `i18n/fr` and commit the translation. Translate the Markdown and JSON files in `i18n/fr` and commit the translation.
@ -142,21 +142,21 @@ npm run build
npm run build -- --locale fr npm run build -- --locale fr
``` ```
### Repeat ### Repeat {#repeat}
Follow the same process for each locale you need to support. Follow the same process for each locale you need to support.
## Maintain the translations ## Maintain the translations {#maintain-the-translations}
Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents. Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents.
### Markdown translations ### Markdown translations {#markdown-translations}
When an untranslated Markdown document is edited, it is **your responsibility to maintain the respective translated files**, and we unfortunately don't have a good way to help you do so. When an untranslated Markdown document is edited, it is **your responsibility to maintain the respective translated files**, and we unfortunately don't have a good way to help you do so.
To keep your translated sites consistent, when the `website/docs/doc1.md` doc is edited, you need **backport these edits** to `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`. To keep your translated sites consistent, when the `website/docs/doc1.md` doc is edited, you need **backport these edits** to `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`.
### JSON translations ### JSON translations {#json-translations}
To help you maintain the JSON translation files, it is possible to run again the [write-translations](../cli.md#docusaurus-write-translations) CLI command: To help you maintain the JSON translation files, it is possible to run again the [write-translations](../cli.md#docusaurus-write-translations) CLI command:
@ -172,7 +172,7 @@ Reset your translations with the `--override` option.
::: :::
### 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`. 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`.

18
website/docs/i18n/i18n-introduction.md
View file

@ -13,13 +13,13 @@ i18n is a new feature (released early 2021), please report any bug you find.
::: :::
## Goals ## Goals {#goals}
It is important to understand the **design decisions** behind the Docusaurus i18n support. It is important to understand the **design decisions** behind the Docusaurus i18n support.
For more context, you can read the initial [RFC](https://github.com/facebook/docusaurus/issues/3317) and [PR](https://github.com/facebook/docusaurus/pull/3325). For more context, you can read the initial [RFC](https://github.com/facebook/docusaurus/issues/3317) and [PR](https://github.com/facebook/docusaurus/pull/3325).
### i18n goals ### i18n goals {#i18n-goals}
The goals of the Docusaurus i18n system are: The goals of the Docusaurus i18n system are:
@ -36,7 +36,7 @@ The goals of the Docusaurus i18n system are:
- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement - **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations) - **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)
### i18n non-goals ### i18n non-goals {#i18n-non-goals}
We don't provide support for: We don't provide support for:
@ -44,9 +44,9 @@ We don't provide support for:
- **Translation SaaS software**: you are responsible to understand the external tools of your choice - **Translation SaaS software**: you are responsible to understand the external tools of your choice
- **Translation of slugs**: technically complicated, little SEO value - **Translation of slugs**: technically complicated, little SEO value
## Translation workflow ## Translation workflow {#translation-workflow}
### Overview ### Overview {#overview}
Overview of the workflow to create a translated Docusaurus website: Overview of the workflow to create a translated Docusaurus website:
@ -54,17 +54,17 @@ Overview of the workflow to create a translated Docusaurus website:
1. **Translate**: put the translation files at the correct filesystem location 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 1. **Deploy**: build and deploy your site using a single or multi-domain strategy
### Translation files ### Translation files {#translation-files}
You will have to work with 2 kind of translation files. You will have to work with 2 kind of translation files.
#### Markdown files #### Markdown files {#markdown-files}
This is the main content of your Docusaurus website. This is the main content of your Docusaurus website.
Markdown and MDX documents are translated as a whole, to fully preserve the translation context, instead of splitting each sentence as a separate string. Markdown and MDX documents are translated as a whole, to fully preserve the translation context, instead of splitting each sentence as a separate string.
#### JSON files #### JSON files {#json-files}
JSON is used to translate: JSON is used to translate:
@ -92,7 +92,7 @@ The choice was made for 2 reasons:
- **Description attribute**: to help translators with additional context - **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)
### Translation files location ### Translation files location {#translation-files-location}
The translation files should be created at the correct filesystem location. The translation files should be created at the correct filesystem location.

32
website/docs/i18n/i18n-tutorial.md
View file

@ -11,11 +11,11 @@ We will add **French** translations to a **newly initialized English Docusaurus
Initialize a new site with `npx @docusaurus/init@latest init website classic` (like [this one](https://github.com/facebook/docusaurus/tree/master/examples/classic)). Initialize a new site with `npx @docusaurus/init@latest init website classic` (like [this one](https://github.com/facebook/docusaurus/tree/master/examples/classic)).
## Configure your site ## Configure your site {#configure-your-site}
Modify `docusaurus.config.js` to add the i18n support for the French language. Modify `docusaurus.config.js` to add the i18n support for the French language.
### Site configuration ### Site configuration {#site-configuration}
Use the [site i18n configuration](./../api/docusaurus.config.js.md#i18n) to declare the i18n locales: Use the [site i18n configuration](./../api/docusaurus.config.js.md#i18n) to declare the i18n locales:
@ -28,7 +28,7 @@ module.exports = {
}; };
``` ```
### Theme configuration ### Theme configuration {#theme-configuration}
Add a **navbar item** of type `localeDropdown` so that users can select the locale they want: Add a **navbar item** of type `localeDropdown` so that users can select the locale they want:
@ -49,7 +49,7 @@ module.exports = {
}; };
``` ```
### Start your site ### Start your site {#start-your-site}
Start your localized site in dev mode, using the locale of your choice: Start your localized site in dev mode, using the locale of your choice:
@ -75,7 +75,7 @@ Each locale is a **distinct standalone single-page-application**: it is not poss
::: :::
## Translate your site ## Translate your site {#translate-your-site}
The French translations will be added in `website/i18n/fr`. The French translations will be added in `website/i18n/fr`.
@ -89,7 +89,7 @@ Hot-reload will work better when editing existing files.
::: :::
### Use the translation APIs ### Use the translation APIs {#use-the-translation-apis}
Open the homepage, and use the [translation APIs](../docusaurus-core.md#translate): Open the homepage, and use the [translation APIs](../docusaurus-core.md#translate):
@ -145,7 +145,7 @@ Most documentation websites are generally **static** and don't need advanced i18
::: :::
### Translate JSON files ### Translate JSON files {#translate-json-files}
JSON translation files are used for everything that is not contained in a Markdown document: JSON translation files are used for everything that is not contained in a Markdown document:
@ -202,11 +202,11 @@ Plugins and themes will also write their own **JSON translation files**, such as
Translate the `message` attribute in the JSON files of `i18n/fr`, and your site layout and homepage should now be translated. Translate the `message` attribute in the JSON files of `i18n/fr`, and your site layout and homepage should now be translated.
### Translate Markdown files ### Translate Markdown files {#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 {#translate-the-docs}
Copy your docs Markdown files to `i18n/fr/docusaurus-plugin-content-docs/current`, and translate them: Copy your docs Markdown files to `i18n/fr/docusaurus-plugin-content-docs/current`, and translate them:
@ -221,7 +221,7 @@ cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
::: :::
#### Translate the blog #### Translate the blog {#translate-the-blog}
Copy your blog Markdown files to `i18n/fr/docusaurus-plugin-content-blog`, and translate them: Copy your blog Markdown files to `i18n/fr/docusaurus-plugin-content-blog`, and translate them:
@ -230,7 +230,7 @@ mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog cp -r blog/** i18n/fr/docusaurus-plugin-content-blog
``` ```
#### Translate the pages #### Translate the pages {#translate-the-pages}
Copy your pages Markdown files to `i18n/fr/docusaurus-plugin-content-pages`, and translate them: Copy your pages Markdown files to `i18n/fr/docusaurus-plugin-content-pages`, and translate them:
@ -246,7 +246,7 @@ We only copy `.md` and `.mdx` files, as pages React components are translated th
::: :::
### Use explicit heading ids ### Use explicit heading ids {#use-explicit-heading-ids}
By default, a Markdown heading `### Hello World` will have a generated id `hello-world`. By default, a Markdown heading `### Hello World` will have a generated id `hello-world`.
@ -267,11 +267,11 @@ For localized sites, it is recommended to use **[explicit heading ids](../guides
::: :::
## Deploy your site ## 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 {#single-domain-deployment}
Run the following command: Run the following command:
@ -305,7 +305,7 @@ This is not always possible, and depends on your host: GitHub Pages can't do thi
::: :::
### Multi-domain deployment ### Multi-domain deployment {#multi-domain-deployment}
You can also build your site for a single locale: You can also build your site for a single locale:
@ -327,7 +327,7 @@ This strategy is **not possible** with Github Pages, as it is only possible to *
::: :::
### Hybrid ### Hybrid {#hybrid}
It is possible to have some locales using sub-paths, and others using subdomains. It is possible to have some locales using sub-paths, and others using subdomains.

16
website/docs/installation.md
View file

@ -11,12 +11,12 @@ Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immedi
::: :::
## Requirements ## Requirements {#requirements}
- [Node.js](https://nodejs.org/en/download/) version >= 12.13.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed - [Node.js](https://nodejs.org/en/download/) version >= 12.13.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed
- [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged. - [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged.
## Scaffold project website ## Scaffold project website {#scaffold-project-website}
The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files. The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.
@ -50,7 +50,7 @@ If you want to skip installing dependencies, use the `--skip-install` option, li
npx @docusaurus/init@latest init my-website classic --skip-install npx @docusaurus/init@latest init my-website classic --skip-install
``` ```
## Project structure ## Project structure {#project-structure}
Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`: 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/`:
@ -80,7 +80,7 @@ my-website
└── yarn.lock └── yarn.lock
``` ```
### Project structure rundown ### Project structure rundown {#project-structure-rundown}
- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md) - `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md)
- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx) - `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx)
@ -91,7 +91,7 @@ my-website
- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them - `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar - `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
## Running the development server ## Running the development server {#running-the-development-server}
To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest changes. To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest changes.
@ -104,7 +104,7 @@ By default, a browser window will open at http://localhost:3000.
Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available. Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.
## Build ## Build {#build}
Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website: Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:
@ -114,7 +114,7 @@ npm run build
and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.mdx) for more details. and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.mdx) for more details.
## Updating your Docusaurus version ## Updating your Docusaurus version {#updating-your-docusaurus-version}
There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version. There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version.
@ -152,6 +152,6 @@ Alternatively, if you are using Yarn, you can do:
yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49 yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49
``` ```
## Problems? ## Problems? {#problems}
Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/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) or [Twitter](https://twitter.com/docusaurus).

20
website/docs/introduction.md
View file

@ -5,7 +5,7 @@ description: Docusaurus was designed from the ground up to be easily installed a
slug: / slug: /
--- ---
## Disclaimer ## Disclaimer {#disclaimer}
Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable. Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable.
@ -32,7 +32,7 @@ Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immedi
- :x: You prefer stability over modernity - :x: You prefer stability over modernity
- :x: You need support for IE11 - :x: You need support for IE11
## A better Docusaurus is coming to town ## A better Docusaurus is coming to town {#a-better-docusaurus-is-coming-to-town}
![Docusaurus Slash Introduction](/img/slash-introducing.svg) ![Docusaurus Slash Introduction](/img/slash-introducing.svg)
@ -42,7 +42,7 @@ Beyond that, Docusaurus 2 is a **performant static site generator** and can be u
While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.** While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.**
## Features ## Features {#features}
Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors. Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors.
@ -76,13 +76,13 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
- ⚡️ **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 - ⚡️ **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 - 🦖 **Accessible** - Attention to accessibility, making your site equally accessible to all users
## Comparison with other tools ## Comparison with other tools {#comparison-with-other-tools}
Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need. Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.
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 to help you navigate through the prismatic choices out there.
### Gatsby ### Gatsby {#gatsby}
Gatsby 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 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.
@ -90,31 +90,31 @@ GraphQL is also pretty core to Gatsby, although you don't necessarily need Graph
Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative. Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
### GitBook ### GitBook {#gitbook}
GitBook 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 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).
Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone. Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
### Jekyll ### Jekyll {#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. 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 build pipeline and optimizations, and ease to setup.
### VuePress ### VuePress {#vuepress}
VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice. VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.
<!-- TODO: Add a Next.js comparison --> <!-- TODO: Add a Next.js comparison -->
## Staying informed ## Staying informed {#staying-informed}
- [GitHub](https://github.com/facebook/docusaurus) - [GitHub](https://github.com/facebook/docusaurus)
- [Twitter](https://twitter.com/docusaurus) - [Twitter](https://twitter.com/docusaurus)
- [Blog](/blog) - [Blog](/blog)
## Something missing? ## Something missing? {#something-missing}
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. 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.

50
website/docs/lifecycle-apis.md
View file

@ -11,15 +11,15 @@ This section is a work in progress.
Lifecycle APIs are shared by Themes and Plugins. Lifecycle APIs are shared by Themes and Plugins.
## `validateOptions({options, validate})` ## `validateOptions({options, validate})` {#validateoptionsoptions-validate}
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. 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.
### `options` ### `options` {#options}
`validateOptions` is called with `options` passed to plugin for validation and normalization. `validateOptions` is called with `options` passed to plugin for validation and normalization.
### `validate` ### `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 argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
@ -63,15 +63,15 @@ export function validateOptions({options, validate}) {
} }
``` ```
## `validateThemeConfig({themeConfig, validate})` ## `validateThemeConfig({themeConfig, validate})` {#validatethemeconfigthemeconfig-validate}
Return validated and normalized configuration for the theme. Return validated and normalized configuration for the theme.
### `themeConfig` ### `themeConfig` {#themeconfig}
`validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization. `validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization.
### `validate` ### `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 argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
@ -115,7 +115,7 @@ export function validateThemeConfig({themeConfig, validate}) {
} }
``` ```
## `getPathsToWatch()` ## `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. 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.
@ -134,7 +134,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `async loadContent()` ## `async loadContent()` {#async-loadcontent}
Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing. Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing.
@ -152,15 +152,15 @@ module.exports = function (context, options) {
}; };
``` ```
## `async contentLoaded({content, actions})` ## `async contentLoaded({content, actions})` {#async-contentloadedcontent-actions}
Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data (optional). Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data (optional).
### `content` ### `content` {#content}
`contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`. `contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`.
### `actions` ### `actions` {#actions}
`actions` contain two functions: `actions` contain two functions:
@ -279,19 +279,19 @@ export default function friendsPlugin(context, options) {
} }
``` ```
## `configureWebpack(config, isServer, utils)` ## `configureWebpack(config, isServer, utils)` {#configurewebpackconfig-isserver-utils}
Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the argument argument. Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the argument argument.
### `config` ### `config` {#config}
`configureWebpack` is called with `config` generated according to client/server build. You may treat this as the base config to be merged with. `configureWebpack` is called with `config` generated according to client/server build. You may treat this as the base config to be merged with.
### `isServer` ### `isServer` {#isserver}
`configureWebpack` will be called both in server build and in client build. The server build receives `true` and the client build receives `false` as `isServer`. `configureWebpack` will be called both in server build and in client build. The server build receives `true` and the client build receives `false` as `isServer`.
### `utils` ### `utils` {#utils}
The initial call to `configureWebpack` also receives a util object consists of three functions: The initial call to `configureWebpack` also receives a util object consists of three functions:
@ -326,7 +326,7 @@ module.exports = function (context, options) {
}; };
``` ```
### Merge strategy ### Merge strategy {#merge-strategy}
We merge the Webpack configuration parts of plugins into the global Webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge). We merge the Webpack configuration parts of plugins into the global Webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
@ -350,7 +350,7 @@ module.exports = function (context, options) {
Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details. Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details.
## `configurePostCss(options)` ## `configurePostCss(options)` {#configurepostcssoptions}
Modifies [`postcssOptions` of `postcss-loader`](https://webpack.js.org/loaders/postcss-loader/#postcssoptions) during the generation of the client bundle. Modifies [`postcssOptions` of `postcss-loader`](https://webpack.js.org/loaders/postcss-loader/#postcssoptions) during the generation of the client bundle.
@ -389,7 +389,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `postBuild(props)` ## `postBuild(props)` {#postbuildprops}
Called when a (production) build finishes. Called when a (production) build finishes.
@ -427,7 +427,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `extendCli(cli)` ## `extendCli(cli)` {#extendclicli}
Register an extra command to enhance the CLI of docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander) object. Register an extra command to enhance the CLI of docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander) object.
@ -449,7 +449,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `injectHtmlTags()` ## `injectHtmlTags()` {#injecthtmltags}
Inject head and/or body HTML tags to Docusaurus generated HTML. Inject head and/or body HTML tags to Docusaurus generated HTML.
@ -516,7 +516,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `getThemePath()` ## `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 calls `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
@ -535,7 +535,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `getTypeScriptThemePath()` ## `getTypeScriptThemePath()` {#gettypescriptthemepath}
Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Instead, this path is purely for swizzling TypeScript theme components. Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Instead, this path is purely for swizzling TypeScript theme components.
@ -561,7 +561,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `getSwizzleComponentList()` ## `getSwizzleComponentList()` {#getswizzlecomponentlist}
Return 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 then all components are considered unstable, if `undefined` is returned then all component are considered stable. Return 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 then all components are considered unstable, if `undefined` is returned then all component are considered stable.
@ -579,7 +579,7 @@ const swizzleAllowedComponents = [
module.exports.getSwizzleComponentList = () => swizzleAllowedComponents; module.exports.getSwizzleComponentList = () => swizzleAllowedComponents;
``` ```
## `getClientModules()` ## `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 in the client bundle. These modules are imported globally before React even renders the initial UI.
@ -606,7 +606,7 @@ For example, the in docusaurus-plugin-content-docs:
In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc. In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc.
--> -->
## Example ## Example {#example}
Here's a mind model for a presumptuous plugin implementation. Here's a mind model for a presumptuous plugin implementation.

2
website/docs/migration/migration-automated.md
View file

@ -50,7 +50,7 @@ The migration CLI updates existing files. Be sure to have commited them first!
::: :::
#### Options #### Options {#options}
You can add option flags to the migration CLI to automatically migrate Markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result. You can add option flags to the migration CLI to automatically migrate Markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.

66
website/docs/migration/migration-manual.md
View file

@ -6,11 +6,11 @@ slug: /migration/manual
This manual migration process should be run after the [automated migration process](./migration-automated.md), to complete the missing parts, or debug issues in the migration CLI output. This manual migration process should be run after the [automated migration process](./migration-automated.md), to complete the missing parts, or debug issues in the migration CLI output.
## Project setup ## Project setup {#project-setup}
### `package.json` ### `package.json` {#packagejson}
#### Scoped package names #### Scoped package names {#scoped-package-names}
In Docusaurus 2, we use scoped package names: In Docusaurus 2, we use scoped package names:
@ -36,7 +36,7 @@ Please use the most recent Docusaurus 2 alpha version, which you can check out [
::: :::
#### CLI commands #### CLI commands {#cli-commands}
Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`). Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`).
@ -85,7 +85,7 @@ A typical Docusaurus 2 `package.json` may look like this:
} }
``` ```
### Update references to the `build` directory ### Update references to the `build` directory {#update-references-to-the-build-directory}
In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`. In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`.
@ -93,7 +93,7 @@ In Docusaurus 2, it is now moved to just `website/build`. Make sure that you upd
If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of `yarn publish-gh-pages` script. If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of `yarn publish-gh-pages` script.
### `.gitignore` ### `.gitignore` {#gitignore}
The `.gitignore` in your `website` should contain: The `.gitignore` in your `website` should contain:
@ -120,13 +120,13 @@ yarn-debug.log*
yarn-error.log* yarn-error.log*
``` ```
### `README` ### `README` {#readme}
The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default [Docusaurus v2 README](https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-init/templates/classic/README.md). The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default [Docusaurus v2 README](https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-init/templates/classic/README.md).
## Site configurations ## Site configurations {#site-configurations}
### `docusaurus.config.js` ### `docusaurus.config.js` {#docusaurusconfigjs}
Rename `siteConfig.js` to `docusaurus.config.js`. Rename `siteConfig.js` to `docusaurus.config.js`.
@ -160,13 +160,13 @@ If you are migrating your Docusaurus v1 website, and there are pending documenta
Refer to migration guide below for each field in `siteConfig.js`. Refer to migration guide below for each field in `siteConfig.js`.
### Updated fields ### Updated fields {#updated-fields}
#### `baseUrl`, `tagline`, `title`, `url`, `favicon`, `organizationName`, `projectName`, `githubHost`, `scripts`, `stylesheets` #### `baseUrl`, `tagline`, `title`, `url`, `favicon`, `organizationName`, `projectName`, `githubHost`, `scripts`, `stylesheets` {#baseurl-tagline-title-url-favicon-organizationname-projectname-githubhost-scripts-stylesheets}
No actions needed, these configuration fields were not modified. No actions needed, these configuration fields were not modified.
#### `colors` #### `colors` {#colors}
Deprecated. We wrote a custom CSS framework for Docusaurus 2 called [Infima](https://infima.dev/) which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`: Deprecated. We wrote a custom CSS framework for Docusaurus 2 called [Infima](https://infima.dev/) which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`:
@ -212,7 +212,7 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
<ColorGenerator/> <ColorGenerator/>
#### `footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible` #### `footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible` {#footericon-copyright-ogimage-twitterimage-docssidenavcollapsible}
Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the `themeConfig` field in your `docusaurus.config.js`: Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the `themeConfig` field in your `docusaurus.config.js`:
@ -236,7 +236,7 @@ module.exports = {
}; };
``` ```
#### `headerIcon`, `headerLinks` #### `headerIcon`, `headerLinks` {#headericon-headerlinks}
In Docusaurus 1, header icon and header links were root fields in `siteConfig`: In Docusaurus 1, header icon and header links were root fields in `siteConfig`:
@ -278,7 +278,7 @@ module.exports = {
}; };
``` ```
#### `algolia` #### `algolia` {#algolia}
```jsx {4-8} title="docusaurus.config.js" ```jsx {4-8} title="docusaurus.config.js"
module.exports = { module.exports = {
@ -294,7 +294,7 @@ module.exports = {
}; };
``` ```
#### `blogSidebarCount` #### `blogSidebarCount` {#blogsidebarcount}
Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead: Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead:
@ -315,11 +315,11 @@ module.exports = {
}; };
``` ```
#### `cname` #### `cname` {#cname}
Deprecated. Create a `CNAME` file in your `static` folder instead with your custom domain. Files in the `static` folder will be copied into the root of the `build` folder during execution of the build command. Deprecated. Create a `CNAME` file in your `static` folder instead with your custom domain. Files in the `static` folder will be copied into the root of the `build` folder during execution of the build command.
#### `customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime` #### `customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime` {#customdocspath-docsurl-editurl-enableupdateby-enableupdatetime}
**BREAKING**: `editUrl` should point to (website) Docusaurus project instead of `docs` directory. **BREAKING**: `editUrl` should point to (website) Docusaurus project instead of `docs` directory.
@ -354,7 +354,7 @@ module.exports = {
}; };
``` ```
#### `gaTrackingId` #### `gaTrackingId` {#gatrackingid}
```jsx {5} title="docusaurus.config.js" ```jsx {5} title="docusaurus.config.js"
module.exports = { module.exports = {
@ -368,7 +368,7 @@ module.exports = {
}; };
``` ```
#### `gaGtag` #### `gaGtag` {#gagtag}
```jsx {5} title="docusaurus.config.js" ```jsx {5} title="docusaurus.config.js"
module.exports = { module.exports = {
@ -382,7 +382,7 @@ module.exports = {
}; };
``` ```
### Removed fields ### Removed fields {#removed-fields}
The following fields are all deprecated, you may remove from your configuration file. The following fields are all deprecated, you may remove from your configuration file.
@ -414,7 +414,7 @@ The following fields are all deprecated, you may remove from your configuration
We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated! We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
## Urls ## Urls {#urls}
In v1, all pages were available with or without the `.html` extension. In v1, all pages were available with or without the `.html` extension.
@ -451,9 +451,9 @@ 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` frontmatter.
## Components ## Components {#components}
### Sidebar ### Sidebar {#sidebar}
In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](../guides/docs/sidebar.md#understanding-sidebar-items) other than document. In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](../guides/docs/sidebar.md#understanding-sidebar-items) other than document.
@ -469,7 +469,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
}, },
``` ```
### Footer ### Footer {#footer}
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it: `website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
@ -495,7 +495,7 @@ module.exports = {
}; };
``` ```
### Pages ### Pages {#pages}
Please refer to [creating pages](guides/creating-pages.md) to learn how Docusaurus 2 pages work. After reading that, notice that you have to move `pages/en` files in v1 to `src/pages` instead. Please refer to [creating pages](guides/creating-pages.md) to learn how Docusaurus 2 pages work. After reading that, notice that you have to move `pages/en` files in v1 to `src/pages` instead.
@ -548,13 +548,13 @@ The following code could be helpful for migration of various pages:
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/) - Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/)
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support) - Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support)
## Content ## Content {#content}
### Replace AUTOGENERATED_TABLE_OF_CONTENTS ### Replace AUTOGENERATED_TABLE_OF_CONTENTS {#replace-autogenerated_table_of_contents}
This feature is replaced by [inline table of content](../guides/markdown-features/markdown-features-inline-toc.mdx) This feature is replaced by [inline table of content](../guides/markdown-features/markdown-features-inline-toc.mdx)
### Update Markdown syntax to be MDX-compatible ### Update Markdown syntax to be MDX-compatible {#update-markdown-syntax-to-be-mdx-compatible}
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. 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.
@ -562,23 +562,23 @@ Frontmatter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-mat
**Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier. **Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier.
### Language-specific code tabs ### Language-specific code tabs {#language-specific-code-tabs}
Refer to the [multi-language support code blocks](../guides/markdown-features/markdown-features-code-blocks.mdx#multi-language-support-code-blocks) section. Refer to the [multi-language support code blocks](../guides/markdown-features/markdown-features-code-blocks.mdx#multi-language-support-code-blocks) section.
### Front matter ### Front matter {#front-matter}
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs. The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field. The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field.
## Deployment ## Deployment {#deployment}
The `CNAME` file used by GitHub Pages is not generated anymore, so be sure you have created it in `/static/CNAME` if you use a custom domain. The `CNAME` file used by GitHub Pages is not generated anymore, so be sure you have created it in `/static/CNAME` if you use a custom domain.
The blog RSS feed is now hosted at `/blog/rss.xml` instead of `/blog/feed.xml`. You may want to configure server-side redirects so that users' subscriptions keep working. The blog RSS feed is now hosted at `/blog/rss.xml` instead of `/blog/feed.xml`. You may want to configure server-side redirects so that users' subscriptions keep working.
## Test your site ## Test your site {#test-your-site}
After migration, your folder structure should look like this: After migration, your folder structure should look like this:

14
website/docs/migration/migration-overview.md
View file

@ -14,7 +14,7 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
We try to make this as easy as possible, and provide a migration cli. We try to make this as easy as possible, and provide a migration cli.
## Docusaurus 1 structure ## Docusaurus 1 structure {#docusaurus-1-structure}
Your Docusaurus 1 site should have the following structure: Your Docusaurus 1 site should have the following structure:
@ -31,7 +31,7 @@ Your Docusaurus 1 site should have the following structure:
└── static └── static
``` ```
## Docusaurus 2 structure ## Docusaurus 2 structure {#docusaurus-2-structure}
After the migration, your Docusaurus 2 site could look like: After the migration, your Docusaurus 2 site could look like:
@ -57,7 +57,7 @@ You are free to put the `/docs` folder anywhere you want after having migrated t
::: :::
## Migration process ## Migration process {#migration-process}
There are multiple things to migrate to obtain a fully functional Docusaurus 2 website: There are multiple things to migrate to obtain a fully functional Docusaurus 2 website:
@ -70,7 +70,7 @@ There are multiple things to migrate to obtain a fully functional Docusaurus 2 w
- versioned docs - versioned docs
- i18n support 🚧 - i18n support 🚧
## Automated migration process ## Automated migration process {#automated-migration-process}
The [migration cli](./migration-automated.md) will handle many things of the migration for you. The [migration cli](./migration-automated.md) will handle many things of the migration for you.
@ -82,13 +82,13 @@ We recommend running the migration cli, and complete the missing parts thanks to
::: :::
## Manual migration process ## Manual migration process {#manual-migration-process}
Some parts of the migration can't be automated (particularly the pages), and you will have to migrate them manually. Some parts of the migration can't be automated (particularly the pages), and you will have to migrate them manually.
The [manual migration guide](./migration-manual.md) will give you all the manual steps. The [manual migration guide](./migration-manual.md) will give you all the manual steps.
## Support ## Support {#support}
For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord channel](https://discordapp.com/invite/kYaNd6V). For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord channel](https://discordapp.com/invite/kYaNd6V).
@ -96,6 +96,6 @@ Feel free to tag [@slorber](https://github.com/slorber) in any migration PRs if
We also have volunteers willing to [help you migrate your v1 site](https://github.com/facebook/docusaurus/issues/1834). We also have volunteers willing to [help you migrate your v1 site](https://github.com/facebook/docusaurus/issues/1834).
## Example migration PRs ## Example migration PRs {#example-migration-prs}
You might want to refer to our migration PRs for [Create React App](https://github.com/facebook/create-react-app/pull/7785) and [Flux](https://github.com/facebook/flux/pull/471) as examples of how a migration for a basic Docusaurus v1 site can be done. You might want to refer to our migration PRs for [Create React App](https://github.com/facebook/create-react-app/pull/7785) and [Flux](https://github.com/facebook/flux/pull/471) as examples of how a migration for a basic Docusaurus v1 site can be done.

8
website/docs/migration/migration-versioned-sites.md
View file

@ -12,7 +12,7 @@ The versioned docs should normally be migrated correctly by the [migration CLI](
::: :::
## Migrate your `versioned_docs` front matter ## Migrate your `versioned_docs` front matter {#migrate-your-versioned_docs-front-matter}
Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation. Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation.
@ -64,7 +64,7 @@ title: Hello, World !
Hi, Endilie here :) Hi, Endilie here :)
``` ```
## Migrate your `versioned_sidebars` ## Migrate your `versioned_sidebars` {#migrate-your-versioned_sidebars}
- Refer to `versioned_docs` id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1). - Refer to `versioned_docs` id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
@ -114,7 +114,7 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`:
} }
``` ```
## Populate your `versioned_sidebars` and `versioned_docs` ## Populate your `versioned_sidebars` and `versioned_docs` {#populate-your-versioned_sidebars-and-versioned_docs}
In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality). In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).
@ -157,7 +157,7 @@ website
│ └── version-1.0.0-sidebars.json │ └── version-1.0.0-sidebars.json
``` ```
## Convert style attributes to style objects in MDX ## Convert style attributes to style objects in MDX {#convert-style-attributes-to-style-objects-in-mdx}
Docusaurus 2 uses JSX for doc files. If you have any style attributes in your Docusaurus 1 docs, convert them to style objects, like this: Docusaurus 2 uses JSX for doc files. If you have any style attributes in your Docusaurus 1 docs, convert them to style objects, like this:

10
website/docs/presets.md
View file

@ -5,7 +5,7 @@ title: Presets
Presets are collections of plugins and themes. Presets are collections of plugins and themes.
## Using presets ## 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 a npm package, so you install them like other npm packages using npm.
@ -33,7 +33,7 @@ module.exports = {
}; };
``` ```
## Presets -> themes and plugins ## Presets -> themes and plugins {#presets---themes-and-plugins}
Presets in some way are a shorthand function to add plugins and themes to your docusaurus config. For example, you can specify a preset that includes the following themes and plugins, Presets in some way are a shorthand function to add plugins and themes to your docusaurus config. For example, you can specify a preset that includes the following themes and plugins,
@ -69,9 +69,9 @@ module.exports = {
This is especially useful when some plugins and themes are intended to be used together. This is especially useful when some plugins and themes are intended to be used together.
## Official presets ## Official presets {#official-presets}
### `@docusaurus/preset-classic` ### `@docusaurus/preset-classic` {#docusauruspreset-classic}
The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes. The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.
@ -133,7 +133,7 @@ module.exports = {
}; };
``` ```
### `@docusaurus/preset-bootstrap` ### `@docusaurus/preset-bootstrap` {#docusauruspreset-bootstrap}
The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes. The classic preset that is usually shipped by default to new docusaurus website. It is a set of plugins and themes.

14
website/docs/search.md
View file

@ -10,13 +10,13 @@ Docusaurus' own `@docusaurus/preset-classic` supports a search integration.
There are two main options, you can use [Algolia DocSearch](https://docsearch.algolia.com) or bring in your own `SearchBar` component. There are two main options, you can use [Algolia DocSearch](https://docsearch.algolia.com) or bring in your own `SearchBar` component.
## Using Algolia DocSearch ## Using Algolia DocSearch {#using-algolia-docsearch}
Algolia DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website needs to be publicly available for this to work (i.e., not behind a firewall). The service is free. Algolia DocSearch works by crawling the content of your website every 24 hours and putting all the content in an Algolia index. This content is then queried directly from your front-end using the Algolia API. Note that your website needs to be publicly available for this to work (i.e., not behind a firewall). The service is free.
If your website is [not eligible](https://docsearch.algolia.com/docs/who-can-apply) for the free, hosted version of DocSearch, or if your website sits behind a firewall, then you can [run your own](https://docsearch.algolia.com/docs/run-your-own/) DocSearch crawler. For best results, you may want to use a config file based on the [Docusaurus 2 config](https://github.com/algolia/docsearch-configs/blob/master/configs/docusaurus-2.json). If your website is [not eligible](https://docsearch.algolia.com/docs/who-can-apply) for the free, hosted version of DocSearch, or if your website sits behind a firewall, then you can [run your own](https://docsearch.algolia.com/docs/run-your-own/) DocSearch crawler. For best results, you may want to use a config file based on the [Docusaurus 2 config](https://github.com/algolia/docsearch-configs/blob/master/configs/docusaurus-2.json).
### Connecting Algolia ### Connecting Algolia {#connecting-algolia}
To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. **[Apply for DocSearch](https://docsearch.algolia.com/apply/)** to get your Algolia index and API key. To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. **[Apply for DocSearch](https://docsearch.algolia.com/apply/)** to get your Algolia index and API key.
@ -49,7 +49,7 @@ The `searchParameters` option used to be named `algoliaOptions` in Docusaurus v1
::: :::
### Contextual search ### Contextual search {#contextual-search}
Contextual search is mostly useful for versioned Docusaurus sites. Contextual search is mostly useful for versioned Docusaurus sites.
@ -80,7 +80,7 @@ When using `contextualSearch: true`, the contextual facet filters will be merged
::: :::
### Styling your Algolia search ### Styling your Algolia search {#styling-your-algolia-search}
By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards. By default, DocSearch comes with a fine-tuned theme that was designed for accessibility, making sure that colors and contrasts respect standards.
@ -128,7 +128,7 @@ html[data-theme='dark'] .DocSearch {
} }
``` ```
### Customizing the Algolia search behavior ### Customizing the Algolia search behavior {#customizing-the-algolia-search-behavior}
<!-- TODO: update options link once the documentation is available on the DocSearch website --> <!-- TODO: update options link once the documentation is available on the DocSearch website -->
@ -147,7 +147,7 @@ module.exports = {
}; };
``` ```
### Editing the Algolia search component ### Editing the Algolia search component {#editing-the-algolia-search-component}
If you prefer to edit the Algolia search React component, swizzle the `SearchBar` component in `@docusaurus/theme-search-algolia`: If you prefer to edit the Algolia search React component, swizzle the `SearchBar` component in `@docusaurus/theme-search-algolia`:
@ -155,7 +155,7 @@ If you prefer to edit the Algolia search React component, swizzle the `SearchBar
npm run swizzle @docusaurus/theme-search-algolia SearchBar npm run swizzle @docusaurus/theme-search-algolia SearchBar
``` ```
## Using your own search ## Using your own search {#using-your-own-search}
To use your own search, swizzle the `SearchBar` component in `@docusaurus/theme-classic` To use your own search, swizzle the `SearchBar` component in `@docusaurus/theme-classic`

8
website/docs/static-assets.md
View file

@ -12,13 +12,13 @@ This means that:
- for site `baseUrl: '/'`, the image `/static/img/docusaurus.png` will be served at `/img/docusaurus.png`. - for site `baseUrl: '/'`, the image `/static/img/docusaurus.png` will be served at `/img/docusaurus.png`.
- for site `baseUrl: '/subpath/'`, the image `/static/img/docusaurus.png` will be served at `/subpath/img/docusaurus.png`. - for site `baseUrl: '/subpath/'`, the image `/static/img/docusaurus.png` will be served at `/subpath/img/docusaurus.png`.
## Referencing your static asset ## Referencing your static asset {#referencing-your-static-asset}
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 link**s. 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 link**s.
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` / `require()` the static asset (recommended), or use the `useBaseUrl` utility function: both prepend the `baseUrl` to paths for you.
### JSX example ### JSX example {#jsx-example}
```jsx title="MyComponent.js" ```jsx title="MyComponent.js"
import DocusaurusImageUrl from '@site/static/img/docusaurus.png'; import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
@ -44,7 +44,7 @@ import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />; <DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
``` ```
### Markdown example ### Markdown example {#markdown-example}
Markdown links and images referencing assets of the static folder will be converted to `require("@site/static/assetName.png")"`, and **the site baseUrl will be automatically prepended** for you. Markdown links and images referencing assets of the static folder will be converted to `require("@site/static/assetName.png")"`, and **the site baseUrl will be automatically prepended** for you.
@ -68,7 +68,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
<img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} /> <img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />
``` ```
### Caveats ### Caveats {#caveats}
Keep in mind that: Keep in mind that:

20
website/docs/styling-layout.md
View file

@ -6,7 +6,7 @@ description: A Docusaurus site is a pre-rendered single-page React application.
import ColorGenerator from '@site/src/components/ColorGenerator'; import ColorGenerator from '@site/src/components/ColorGenerator';
## Traditional CSS ## Traditional CSS {#traditional-css}
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 it as an option into the preset.
@ -30,7 +30,7 @@ module.exports = {
Any CSS you write within that file will be available globally and can be referenced directly using string literals. This is the most traditional approach to writing CSS and is fine for small websites that do not have much customization. Any CSS you write within that file will be available globally and can be referenced directly using string literals. This is the most traditional approach to writing CSS and is fine for small websites that do not have much customization.
## Styling your site with Infima ## 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 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/).
@ -59,7 +59,7 @@ Alternatively, use the following tool to generate the different shades for your
<ColorGenerator/> <ColorGenerator/>
### Dark Mode ### 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`.
@ -73,13 +73,13 @@ html[data-theme='dark'] {
<!-- TODO need more refinement here --> <!-- TODO need more refinement here -->
## Styling approaches ## Styling approaches {#styling-approaches}
A Docusaurus site is a single-page React application. You can style it the way you style React apps. 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 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.
### Global styles ### Global styles {#global-styles}
This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with. This is the most traditional way of styling that most developers (including non-front end developers) would be familiar with.
@ -101,7 +101,7 @@ function MyComponent() {
} }
``` ```
### CSS modules ### CSS modules {#css-modules}
To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet). To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).
@ -134,7 +134,7 @@ function MyComponent() {
The class names which will be processed by webpack into a globally unique class name during build. The class names which will be processed by webpack into a globally unique class name during build.
### CSS-in-JS ### CSS-in-JS {#css-in-js}
:::caution :::caution
@ -142,7 +142,7 @@ This section is a work in progress. [Welcoming PRs](https://github.com/facebook/
::: :::
### Sass/SCSS ### Sass/SCSS {#sassscss}
To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass). This plugin works for both global styles and the CSS modules approach: To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass). This plugin works for both global styles and the CSS modules approach:
@ -164,7 +164,7 @@ module.exports = {
3. Write and import your stylesheets in Sass/SCSS as normal. 3. Write and import your stylesheets in Sass/SCSS as normal.
#### Global styles using Sass/SCSS #### Global styles using Sass/SCSS {#global-styles-using-sassscss}
You can now set the `customCss` property of `@docusaurus/preset-classic` to point to your Sass/SCSS file: You can now set the `customCss` property of `@docusaurus/preset-classic` to point to your Sass/SCSS file:
@ -185,7 +185,7 @@ module.exports = {
}; };
``` ```
#### Modules using Sass/SCSS #### Modules using Sass/SCSS {#modules-using-sassscss}
Name your stylesheet files with the `.module.scss` suffix (e.g. `welcome.module.scss`) instead of `.css`. Webpack will use `sass-loader` to preprocess your stylesheets and load them as CSS modules. Name your stylesheet files with the `.module.scss` suffix (e.g. `welcome.module.scss`) instead of `.css`. Webpack will use `sass-loader` to preprocess your stylesheets and load them as CSS modules.

4
website/docs/typescript-support.md
View file

@ -3,7 +3,7 @@ id: typescript-support
title: TypeScript Support title: TypeScript Support
--- ---
## Setup ## Setup {#setup}
Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add `@docusaurus/module-type-aliases` and some `@types` dependencies to your project: Docusaurus supports writing and using TypeScript theme components. To start using TypeScript, add `@docusaurus/module-type-aliases` and some `@types` dependencies to your project:
@ -24,7 +24,7 @@ Docusaurus doesn't use this `tsconfig.json` to compile your project. It is added
Now you can start writing TypeScript theme components. Now you can start writing TypeScript theme components.
## Swizzling TypeScript theme components ## Swizzling TypeScript theme components {#swizzling-typescript-theme-components}
For themes that supports TypeScript theme components, you can add the `--typescript` flag to the end of swizzling command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`. 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`.

20
website/docs/using-plugins.md
View file

@ -5,11 +5,11 @@ 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 bundle via [presets](presets.md).
## Available plugins ## Available plugins {#available-plugins}
We maintain a [list of official plugins](./api/plugins/overview.md), but the community has also created some [unofficial plugins](/community/resources#community-plugins). We maintain a [list of official plugins](./api/plugins/overview.md), but the community has also created some [unofficial plugins](/community/resources#community-plugins).
## Installing a plugin ## Installing a plugin {#installing-a-plugin}
A plugin is usually a npm package, so you install them like other npm packages using npm. A plugin is usually a npm package, so you install them like other npm packages using npm.
@ -37,7 +37,7 @@ module.exports = {
}; };
``` ```
## Configuring plugins ## Configuring plugins {#configuring-plugins}
For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin. For the most basic usage of plugins, you can provide just the plugin name or the absolute path to the plugin.
@ -76,7 +76,7 @@ module.exports = {
}; };
``` ```
## Multi-instance plugins and plugin ids ## Multi-instance plugins and plugin ids {#multi-instance-plugins-and-plugin-ids}
All Docusaurus content plugins can support multiple plugin instances. All Docusaurus content plugins can support multiple plugin instances.
@ -113,15 +113,15 @@ At most one plugin instance can be the "default plugin instance", by omitting th
::: :::
## Plugins design ## 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 not limited to) extending the webpack config, modifying the data being loaded and creating new components to be used in a page.
## Creating plugins ## Creating plugins {#creating-plugins}
A plugin is a module which exports a function that takes two parameters and returns an object when executed. A plugin is a module which exports a function that takes two parameters and returns an object when executed.
### Module definition ### Module definition {#module-definition}
The exported modules for plugins are called with two parameters: `context` and `options` and returns a JavaScript object with defining the [lifecycle APIs](./lifecycle-apis.md). The exported modules for plugins are called with two parameters: `context` and `options` and returns a JavaScript object with defining the [lifecycle APIs](./lifecycle-apis.md).
@ -154,7 +154,7 @@ module.exports = function (context, options) {
The `my-plugin` folder could also be a fully fledged package with it's own package.json and a `src/index.js` file for example The `my-plugin` folder could also be a fully fledged package with it's own package.json and a `src/index.js` file for example
#### `context` #### `context` {#context}
`context` is plugin-agnostic and the same object will be passed into all plugins used for a Docusaurus website. The `context` object contains the following fields: `context` is plugin-agnostic and the same object will be passed into all plugins used for a Docusaurus website. The `context` object contains the following fields:
@ -168,10 +168,10 @@ interface LoadContext {
} }
``` ```
#### `options` #### `options` {#options}
`options` are the [second optional parameter when the plugins are used](using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes. `options` are the [second optional parameter when the plugins are used](using-plugins.md#configuring-plugins). `options` are plugin-specific and are specified by users when they use them in `docusaurus.config.js`. Alternatively, if preset contains the plugin, the preset will then be in charge of passing the correct options into the plugin. It is up to individual plugin to define what options it takes.
#### Return value #### Return value {#return-value}
The returned object value should implement the [lifecycle APIs](lifecycle-apis.md). The returned object value should implement the [lifecycle APIs](lifecycle-apis.md).

20
website/docs/using-themes.md
View file

@ -5,11 +5,11 @@ 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 client-side, where plugins are more focused on server-side functionalities. Themes are also designed to be replace-able with other themes.
## Available themes ## Available themes {#available-themes}
We maintain a [list of official themes](./api/themes/overview.md). We maintain a [list of official themes](./api/themes/overview.md).
## Using themes ## Using themes {#using-themes}
To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes: To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes:
@ -20,7 +20,7 @@ module.exports = {
}; };
``` ```
## Theme components ## Theme components {#theme-components}
Most of the time, theme is used to provide a set of React components, e.g. `Navbar`, `Layout`, `Footer`. Most of the time, theme is used to provide a set of React components, e.g. `Navbar`, `Layout`, `Footer`.
@ -71,7 +71,7 @@ And if you want to use Bootstrap styling, you can swap out the theme with `theme
} }
``` ```
## Wrapper your site with `<Root>` ## Wrapper your site with `<Root>` {#wrapper-your-site-with-root}
A `<Root>` theme component is rendered at the very top of your Docusaurus site. A `<Root>` theme component is rendered at the very top of your Docusaurus site.
@ -96,7 +96,7 @@ Use this component render React Context providers and global stateful logic.
::: :::
## Swizzling theme components ## Swizzling theme components {#swizzling-theme-components}
:::caution :::caution
@ -128,13 +128,13 @@ npm run swizzle @docusaurus/theme-classic
**Note**: You need to restart your webpack dev server in order for Docusaurus to know about the new component. **Note**: You need to restart your webpack dev server in order for Docusaurus to know about the new component.
## Wrapping theme components ## Wrapping theme components {#wrapping-theme-components}
Sometimes, you just want to wrap an existing theme component with additional logic, and it can be a pain to have to maintain an almost duplicate copy of the original theme component. 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 such case, you should swizzle the component you want to wrap, but import the original theme component in your customized version to wrap it.
### For site owners ### For site owners {#for-site-owners}
The `@theme-original` alias allows you to import the original theme component. The `@theme-original` alias allows you to import the original theme component.
@ -155,7 +155,7 @@ export default function Footer(props) {
} }
``` ```
### For plugin authors ### For plugin authors {#for-plugin-authors}
One theme can wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import. One theme can wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import.
@ -182,7 +182,7 @@ Unless you want publish to npm a "theme enhancer" (like `docusaurus-theme-live-c
::: :::
## Themes design ## Themes design {#themes-design}
While themes share the exact same lifecycle methods with plugins, their implementations can look very different from those of plugins based on themes' designed objectives. 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.
@ -194,7 +194,7 @@ To summarize:
- Themes are run after all existing Plugins - Themes are run after all existing Plugins
- Themes exist to add component aliases by extending the webpack config - Themes exist to add component aliases by extending the webpack config
## Writing customized Docusaurus themes ## 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 with a `theme/` directory of components. A typical Docusaurus `theme` folder looks like this:

54
website/versioned_docs/version-2.0.0-alpha.71/api/docusaurus.config.js.md
View file

@ -5,13 +5,13 @@ description: API reference for Docusaurus configuration file.
slug: /docusaurus.config.js slug: /docusaurus.config.js
--- ---
## Overview ## Overview {#overview}
`docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site. `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
## Required fields ## Required fields {#required-fields}
### `title` ### `title` {#title}
- Type: `string` - Type: `string`
@ -23,7 +23,7 @@ module.exports = {
}; };
``` ```
### `favicon` ### `favicon` {#favicon}
- Type: `string` - Type: `string`
@ -54,7 +54,7 @@ module.exports = {
}; };
``` ```
### `url` ### `url` {#url}
- Type: `string` - Type: `string`
@ -66,7 +66,7 @@ module.exports = {
}; };
``` ```
### `baseUrl` ### `baseUrl` {#baseurl}
- Type: `string` - Type: `string`
@ -78,9 +78,9 @@ module.exports = {
}; };
``` ```
## Optional fields ## Optional fields {#optional-fields}
### `i18n` ### `i18n` {#i18n}
- Type: `Object` - Type: `Object`
@ -110,7 +110,7 @@ module.exports = {
- `label`: the label to use for this locale - `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 Araric, Hebrew, etc.)
### `noIndex` ### `noIndex` {#noindex}
- Type: `boolean` - Type: `boolean`
@ -124,7 +124,7 @@ module.exports = {
}; };
``` ```
### `onBrokenLinks` ### `onBrokenLinks` {#onbrokenlinks}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
@ -138,7 +138,7 @@ The broken links detection is only available for a production build (`docusaurus
::: :::
### `onBrokenMarkdownLinks` ### `onBrokenMarkdownLinks` {#onbrokenmarkdownlinks}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
@ -146,7 +146,7 @@ The behavior of Docusaurus, when it detects any broken markdown link.
By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed. By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed.
### `onDuplicateRoutes` ### `onDuplicateRoutes` {#onduplicateroutes}
- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'` - Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
@ -154,7 +154,7 @@ The behavior of Docusaurus when it detects any [duplicate routes](/guides/creati
By default, it displays a warning after you run `yarn start` or `yarn build`. By default, it displays a warning after you run `yarn start` or `yarn build`.
### `tagline` ### `tagline` {#tagline}
- Type: `string` - Type: `string`
@ -167,7 +167,7 @@ module.exports = {
}; };
``` ```
### `organizationName` ### `organizationName` {#organizationname}
- Type: `string` - Type: `string`
@ -180,7 +180,7 @@ module.exports = {
}; };
``` ```
### `projectName` ### `projectName` {#projectname}
- Type: `string` - Type: `string`
@ -192,7 +192,7 @@ module.exports = {
}; };
``` ```
### `githubHost` ### `githubHost` {#githubhost}
- Type: `string` - Type: `string`
@ -204,7 +204,7 @@ module.exports = {
}; };
``` ```
### `themeConfig` ### `themeConfig` {#themeconfig}
- Type: `Object` - Type: `Object`
@ -273,7 +273,7 @@ module.exports = {
}; };
``` ```
### `plugins` ### `plugins` {#plugins}
<!-- TODO: configuration for plugins --> <!-- TODO: configuration for plugins -->
@ -285,7 +285,7 @@ module.exports = {
}; };
``` ```
### `themes` ### `themes` {#themes}
<!-- TODO: configuration for plugins --> <!-- TODO: configuration for plugins -->
@ -297,7 +297,7 @@ module.exports = {
}; };
``` ```
### `presets` ### `presets` {#presets}
<!-- TODO: configuration for presets --> <!-- TODO: configuration for presets -->
@ -309,7 +309,7 @@ module.exports = {
}; };
``` ```
### `customFields` ### `customFields` {#customfields}
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`. Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, define it on `customFields`.
@ -330,7 +330,7 @@ Attempting to add unknown field in the config will lead to error in build time:
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
``` ```
### `scripts` ### `scripts` {#scripts}
An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`. An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`.
@ -355,7 +355,7 @@ module.exports = {
}; };
``` ```
### `clientModules` ### `clientModules` {#clientmodules}
An array of client modules to load globally on your site: An array of client modules to load globally on your site:
@ -372,7 +372,7 @@ module.exports = {
See also: [`getClientModules()`](lifecycle-apis.md#getclientmodules). See also: [`getClientModules()`](lifecycle-apis.md#getclientmodules).
### `ssrTemplate` ### `ssrTemplate` {#ssrtemplate}
An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview) that will be used to render your application. This can be used to set custom attributes on the `body` tags, additional `meta` tags, customize the `viewport`, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from `upstream`. An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview) that will be used to render your application. This can be used to set custom attributes on the `body` tags, additional `meta` tags, customize the `viewport`, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from `upstream`.
@ -416,7 +416,7 @@ module.exports = {
}; };
``` ```
### `stylesheets` ### `stylesheets` {#stylesheets}
An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`. An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`.
@ -438,7 +438,7 @@ module.exports = {
}; };
``` ```
### `titleDelimiter` ### `titleDelimiter` {#titledelimiter}
- Type: `string` - Type: `string`
@ -452,7 +452,7 @@ module.exports = {
}; };
``` ```
### `baseUrlIssueBanner` ### `baseUrlIssueBanner` {#baseurlissuebanner}
- Type: `boolean` - Type: `boolean`

4
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/overview.md
View file

@ -7,7 +7,7 @@ slug: '/api/plugins'
We provide official Docusaurus plugins. We provide official Docusaurus plugins.
## Content plugins ## Content plugins {#content-plugins}
These plugins are responsible to load your site's content, and create pages for your theme to render. These plugins are responsible to load your site's content, and create pages for your theme to render.
@ -15,7 +15,7 @@ These plugins are responsible to load your site's content, and create pages for
- [@docusaurus/plugin-content-blog](./plugin-content-blog.md) - [@docusaurus/plugin-content-blog](./plugin-content-blog.md)
- [@docusaurus/plugin-content-pages](./plugin-content-pages.md) - [@docusaurus/plugin-content-pages](./plugin-content-pages.md)
## Behavior plugins ## Behavior plugins {#behavior-plugins}
These plugins will add a useful behavior to your Docusaurus site. These plugins will add a useful behavior to your Docusaurus site.

4
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-client-redirects.md
View file

@ -22,13 +22,13 @@ Before using this plugin, you should look if your hosting provider doesn't offer
::: :::
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-client-redirects npm install --save @docusaurus/plugin-client-redirects
``` ```
## Configuration ## Configuration {#configuration}
Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`: Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`:

10
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-content-blog.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-content-blog'
Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus. Provides the [Blog](blog.md) feature and is the default blog plugin for Docusaurus.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-content-blog npm install --save @docusaurus/plugin-content-blog
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
@ -118,18 +118,18 @@ module.exports = {
}; };
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-blog` - **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>` - **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>`
- **JSON files**: N/A - **JSON files**: N/A
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-blog` - **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-blog`
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-plugin-content-blog website/i18n/<locale>/docusaurus-plugin-content-blog

12
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-content-docs.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-content-docs'
Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus. Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-content-docs npm install --save @docusaurus/plugin-content-docs
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
@ -148,7 +148,7 @@ module.exports = {
}; };
``` ```
## Markdown Frontmatter ## Markdown Frontmatter {#markdown-frontmatter}
Markdown documents can use the following markdown frontmatter metadata fields, enclosed by a line `---` on either side: Markdown documents can use the following markdown frontmatter metadata fields, enclosed by a line `---` on either side:
@ -183,18 +183,18 @@ slug: /myDoc
My Document Markdown content My Document Markdown content
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-docs` - **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-docs`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>` - **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-docs-<pluginId>`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations) - **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-docs/<version>` - **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-docs/<version>`
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-plugin-content-docs website/i18n/<locale>/docusaurus-plugin-content-docs

10
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-content-pages.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-content-pages'
The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality. The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-content-pages npm install --save @docusaurus/plugin-content-pages
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {
@ -67,18 +67,18 @@ module.exports = {
}; };
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-pages` - **Base path**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
- **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-pages-<pluginId>` - **Multi-instance path**: `website/i18n/<locale>/docusaurus-plugin-content-pages-<pluginId>`
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations) - **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-pages` - **Markdown files**: `website/i18n/<locale>/docusaurus-plugin-content-pages`
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-plugin-content-pages website/i18n/<locale>/docusaurus-plugin-content-pages

4
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-debug.md
View file

@ -16,7 +16,7 @@ If you don't have any sensitive information, you can keep it on in production [l
::: :::
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-debug npm install --save @docusaurus/plugin-debug
@ -30,7 +30,7 @@ By default, it's enabled in dev, and disabled in prod, to avoid exposing potenti
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

4
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-google-analytics.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-google-analytics'
The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website. The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-google-analytics npm install --save @docusaurus/plugin-google-analytics
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

4
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-google-gtag.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-google-gtag'
The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics. The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-google-gtag npm install --save @docusaurus/plugin-google-gtag
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

8
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-ideal-image.md
View file

@ -6,13 +6,13 @@ slug: '/api/plugins/@docusaurus/plugin-ideal-image'
Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**. Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder) **in the production builds**.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-ideal-image npm install --save @docusaurus/plugin-ideal-image
``` ```
## Configuration ## Configuration {#configuration}
Modify your `docusaurus.config.js` Modify your `docusaurus.config.js`
@ -24,7 +24,7 @@ module.exports = {
} }
``` ```
## Usage ## Usage {#usage}
This plugin supports the PNG, GIF and JPG formats only. This plugin supports the PNG, GIF and JPG formats only.
@ -39,7 +39,7 @@ import thumbnail from './path/to/img.png';
<Image img={require('./path/to/img.png')} /> <Image img={require('./path/to/img.png')} />
``` ```
## Options ## Options {#options}
| Option | Type | Default | Description | | Option | Type | Default | Description |
| --- | --- | --- | --- | | --- | --- | --- | --- |

26
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-pwa.md
View file

@ -6,13 +6,13 @@ slug: '/api/plugins/@docusaurus/plugin-pwa'
Docusaurus Plugin to add PWA support using [Workbox](https://developers.google.com/web/tools/workbox). This plugin generates a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers) in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support. Docusaurus Plugin to add PWA support using [Workbox](https://developers.google.com/web/tools/workbox). This plugin generates a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers) in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-pwa npm install --save @docusaurus/plugin-pwa
``` ```
## Configuration ## Configuration {#configuration}
Create a [PWA manifest](https://web.dev/add-manifest/) at `./static/manifest.json`. Create a [PWA manifest](https://web.dev/add-manifest/) at `./static/manifest.json`.
@ -49,7 +49,7 @@ module.exports = {
}; };
``` ```
## Progressive Web App ## Progressive Web App {#progressive-web-app}
Having a service worker installed is not enough to make your application a PWA. You'll need to at least include a [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and have the correct tags in `<head>` ([Options > pwaHead](#pwahead)). Having a service worker installed is not enough to make your application a PWA. You'll need to at least include a [Web App Manifest](https://developer.mozilla.org/en-US/docs/Web/Manifest) and have the correct tags in `<head>` ([Options > pwaHead](#pwahead)).
@ -57,13 +57,13 @@ After deployment, you can use [Lighthouse](https://developers.google.com/web/too
For a more exhaustive list of what it takes for your site to be a PWA, refer to the [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist) For a more exhaustive list of what it takes for your site to be a PWA, refer to the [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist)
## App installation support ## App installation support {#app-installation-support}
If your browser supports it, you should be able to install a Docusaurus site as an app. If your browser supports it, you should be able to install a Docusaurus site as an app.
![pwa_install.gif](/img/pwa_install.gif) ![pwa_install.gif](/img/pwa_install.gif)
## Offline mode (precaching) ## Offline mode (precaching) {#offline-mode-precaching}
We enable users to browse a Docusaurus site offline, by using service-worker precaching. We enable users to browse a Docusaurus site offline, by using service-worker precaching.
@ -85,9 +85,9 @@ Offline mode / precaching requires downloading all the static assets of the site
::: :::
## Options ## Options {#options}
### `debug` ### `debug` {#debug}
- Type: `boolean` - Type: `boolean`
- Default: `false` - Default: `false`
@ -99,7 +99,7 @@ Turn debug mode on:
- Unoptimized SW file output - Unoptimized SW file output
- Source maps - Source maps
### `offlineModeActivationStrategies` ### `offlineModeActivationStrategies` {#offlinemodeactivationstrategies}
- Type: `Array<'appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always'>` - Type: `Array<'appInstalled' | 'mobile' | 'saveData'| 'queryString' | 'always'>`
- Default: `['appInstalled','queryString']` - Default: `['appInstalled','queryString']`
@ -118,7 +118,7 @@ Use this carefully: some users may not like to be forced to use the offline mode
::: :::
### `injectManifestConfig` ### `injectManifestConfig` {#injectmanifestconfig}
[Workbox options](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.injectManifest) to pass to `workbox.injectManifest()`. This gives you control over which assets will be precached, and be available offline. [Workbox options](https://developers.google.com/web/tools/workbox/reference-docs/latest/module-workbox-build#.injectManifest) to pass to `workbox.injectManifest()`. This gives you control over which assets will be precached, and be available offline.
@ -149,7 +149,7 @@ module.exports = {
}; };
``` ```
### `reloadPopup` ### `reloadPopup` {#reloadpopup}
- Type: `string | false` - Type: `string | false`
- Default: `'@theme/PwaReloadPopup'` - Default: `'@theme/PwaReloadPopup'`
@ -170,7 +170,7 @@ The default theme includes an implementation for the reload popup and uses [Infi
![pwa_reload.gif](/img/pwa_reload.gif) ![pwa_reload.gif](/img/pwa_reload.gif)
### `pwaHead` ### `pwaHead` {#pwahead}
- Type: `Array<{ tagName: string } & Record<string,string>>` - Type: `Array<{ tagName: string } & Record<string,string>>`
- Default: `[]` - Default: `[]`
@ -237,7 +237,7 @@ module.exports = {
}; };
``` ```
### `swCustom` ### `swCustom` {#swcustom}
- Type: `string | undefined` - Type: `string | undefined`
- Default: `undefined` - Default: `undefined`
@ -270,7 +270,7 @@ export default function swCustom(params) {
The module should have a `default` function export, and receives some params. The module should have a `default` function export, and receives some params.
### `swRegister` ### `swRegister` {#swregister}
- Type: `string | false` - Type: `string | false`
- Default: `'docusaurus-plugin-pwa/src/registerSW.js'` - Default: `'docusaurus-plugin-pwa/src/registerSW.js'`

4
website/versioned_docs/version-2.0.0-alpha.71/api/plugins/plugin-sitemap.md
View file

@ -6,7 +6,7 @@ slug: '/api/plugins/@docusaurus/plugin-sitemap'
This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately. This plugin creates sitemap for your site so that search engine crawlers can crawl your site more accurately.
## Installation ## Installation {#installation}
```bash npm2yarn ```bash npm2yarn
npm install --save @docusaurus/plugin-sitemap npm install --save @docusaurus/plugin-sitemap
@ -18,7 +18,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
::: :::
## Configuration ## Configuration {#configuration}
```js title="docusaurus.config.js" ```js title="docusaurus.config.js"
module.exports = { module.exports = {

4
website/versioned_docs/version-2.0.0-alpha.71/api/themes/overview.md
View file

@ -7,7 +7,7 @@ slug: '/api/themes'
We provide official Docusaurus themes. We provide official Docusaurus themes.
## Main themes ## Main themes {#main-themes}
The main themes implement the user interface for the [docs](../plugins/plugin-content-docs.md), [blog](../plugins/plugin-content-blog.md) and [pages](../plugins/plugin-content-pages.md) plugins. The main themes implement the user interface for the [docs](../plugins/plugin-content-docs.md), [blog](../plugins/plugin-content-blog.md) and [pages](../plugins/plugin-content-pages.md) plugins.
@ -24,7 +24,7 @@ We are not there yet: only the classic theme is production ready.
::: :::
## Enhancement themes ## Enhancement themes {#enhancement-themes}
These themes will enhance the existing main themes with additional user-interface related features. These themes will enhance the existing main themes with additional user-interface related features.

54
website/versioned_docs/version-2.0.0-alpha.71/api/themes/theme-configuration.md
View file

@ -6,9 +6,9 @@ slug: '/api/themes/configuration'
This configuration applies to all [main themes](./overview.md). This configuration applies to all [main themes](./overview.md).
## Common ## Common {#common}
### Color mode - dark mode ### Color mode - dark mode {#color-mode---dark-mode}
The classic theme provides by default light and dark mode support, with a navbar switch for the user. The classic theme provides by default light and dark mode support, with a navbar switch for the user.
@ -66,7 +66,7 @@ If you only want to support one color mode, you likely want to ignore user syste
::: :::
### Meta image ### Meta image {#meta-image}
You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`. You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.
@ -82,7 +82,7 @@ module.exports = {
}; };
``` ```
### Metadatas ### Metadatas {#metadatas}
You can configure additional html metadatas (and override existing ones). You can configure additional html metadatas (and override existing ones).
@ -96,7 +96,7 @@ module.exports = {
}; };
``` ```
### Announcement bar ### Announcement bar {#announcement-bar}
Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar. Sometimes you want to announce something in your website. Just for such a case, you can add an announcement bar. This is a non-fixed and optionally dismissable panel above the navbar.
@ -117,18 +117,18 @@ module.exports = {
}; };
``` ```
## i18n ## i18n {#i18n}
Read the [i18n introduction](../../i18n/i18n-introduction.md) first. Read the [i18n introduction](../../i18n/i18n-introduction.md) first.
### Translation files location ### Translation files location {#translation-files-location}
- **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>` - **Base path**: `website/i18n/<locale>/docusaurus-theme-<themeName>`
- **Multi-instance path**: N/A - **Multi-instance path**: N/A
- **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations) - **JSON files**: extracted with [`docusaurus write-translations`](../../cli.md#docusaurus-write-translations)
- **Markdown files**: `N/A - **Markdown files**: `N/A
### Example file-system structure ### Example file-system structure {#example-file-system-structure}
```bash ```bash
website/i18n/<locale>/docusaurus-theme-classic website/i18n/<locale>/docusaurus-theme-classic
@ -138,9 +138,9 @@ website/i18n/<locale>/docusaurus-theme-classic
└── footer.json └── footer.json
``` ```
## Hooks ## Hooks {#hooks}
### `useThemeContext` ### `useThemeContext` {#usethemecontext}
React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use. React hook to access theme context. This context contains functions for setting light and dark mode and boolean property, indicating which mode is currently in use.
@ -175,9 +175,9 @@ function ExamplePage() {
::: :::
## Navbar ## Navbar {#navbar}
### Navbar title & logo ### Navbar title & logo {#navbar-title--logo}
You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab. You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be placed in [static folder](static-assets.md). Logo URL is set to base URL of your site by default. Although you can specify your own URL for the logo, if it is an external link, it will open in a new tab. In addition, you can override a value for the target attribute of logo link, it can come in handy if you are hosting docs website in a subdirectory of your main website, and in which case you probably do not need a link in the logo to the main website will open in a new tab.
@ -202,7 +202,7 @@ module.exports = {
}; };
``` ```
### Navbar items ### Navbar items {#navbar-items}
You can add items to the navbar via `themeConfig.navbar.items`. You can add items to the navbar via `themeConfig.navbar.items`.
@ -250,7 +250,7 @@ React Router should automatically apply active link styling to links, but you ca
Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes. Outbound (external) links automatically get `target="_blank" rel="noopener noreferrer"` attributes.
### Navbar dropdown ### Navbar dropdown {#navbar-dropdown}
Navbar items can also be dropdown items by specifying the `items`, an inner array of navbar items. Navbar items can also be dropdown items by specifying the `items`, an inner array of navbar items.
@ -282,7 +282,7 @@ module.exports = {
}; };
``` ```
### Navbar doc link ### Navbar doc link {#navbar-doc-link}
If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided `docId`. It will get the class `navbar__link--active` as long as you browse a doc of the same sidebar. If you want to link to a specific doc, this special navbar item type will render the link to the doc of the provided `docId`. It will get the class `navbar__link--active` as long as you browse a doc of the same sidebar.
@ -309,7 +309,7 @@ module.exports = {
}; };
``` ```
### Navbar docs version dropdown ### Navbar docs version dropdown {#navbar-docs-version-dropdown}
If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions. If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.
@ -338,7 +338,7 @@ module.exports = {
}; };
``` ```
### Navbar docs version ### Navbar docs version {#navbar-docs-version}
If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version. If you use docs with versioning, this special navbar item type will link to the active/browsed version of your doc (depends on the current url), and fallback to the latest version.
@ -364,7 +364,7 @@ module.exports = {
}; };
``` ```
### Navbar locale dropdown ### Navbar locale dropdown {#navbar-locale-dropdown}
If you use the [i18n feature](../../i18n/i18n-introduction.md), this special navbar item type will render a dropdown with all your site's available locales. If you use the [i18n feature](../../i18n/i18n-introduction.md), this special navbar item type will render a dropdown with all your site's available locales.
@ -395,7 +395,7 @@ module.exports = {
}; };
``` ```
### Navbar search ### Navbar search {#navbar-search}
If you use the [search](../../search.md), the search bar will be the rightmost element in the navbar. If you use the [search](../../search.md), the search bar will be the rightmost element in the navbar.
@ -416,7 +416,7 @@ module.exports = {
}; };
``` ```
### Auto-hide sticky navbar ### Auto-hide sticky navbar {#auto-hide-sticky-navbar}
You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up. You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.
@ -432,7 +432,7 @@ module.exports = {
}; };
``` ```
### Navbar style ### Navbar style {#navbar-style}
You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected. You can set the static Navbar style without disabling the theme switching ability. The selected style will always apply no matter which theme user have selected.
@ -452,17 +452,17 @@ module.exports = {
<!-- <!--
## Footer ## Footer {#footer}
TODO. TODO.
--> -->
## CodeBlock ## CodeBlock {#codeblock}
Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks.
### Theme ### Theme {#theme}
By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so. By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.
@ -485,7 +485,7 @@ If you use the line highlighting Markdown syntax, you might need to specify a di
::: :::
### Default language ### Default language {#default-language}
You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.: You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.:
@ -501,7 +501,7 @@ module.exports = {
}; };
``` ```
## Footer ## Footer {#footer-1}
You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo. You can add logo and a copyright to the footer via `themeConfig.footer`. Logo can be placed in [static folder](static-assets.md). Logo URL works in the same way of the navbar logo.
@ -517,7 +517,7 @@ You can add logo and a copyright to the footer via `themeConfig.footer`. Logo ca
} }
``` ```
## Footer Links ## Footer Links {#footer-links}
You can add links to the navbar via `themeConfig.footer.links`: You can add links to the navbar via `themeConfig.footer.links`:

2
website/versioned_docs/version-2.0.0-alpha.71/api/themes/theme-live-codeblock.md
View file

@ -10,7 +10,7 @@ This theme provides a `@theme/CodeBlock` component that is powered by react-live
npm install --save @docusaurus/theme-live-codeblock npm install --save @docusaurus/theme-live-codeblock
``` ```
### Configuration ### Configuration {#configuration}
```jsx title="docusaurus.config.js" ```jsx title="docusaurus.config.js"
module.exports = { module.exports = {

16
website/versioned_docs/version-2.0.0-alpha.71/blog.md
View file

@ -3,7 +3,7 @@ id: blog
title: Blog title: Blog
--- ---
## Initial setup ## Initial setup {#initial-setup}
To setup your site's blog, start by creating a `blog` directory. To setup your site's blog, start by creating a `blog` directory.
@ -24,7 +24,7 @@ module.exports = {
}; };
``` ```
## Adding posts ## Adding posts {#adding-posts}
To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-my-blog-post-title.md`. The post date is extracted from the file name. To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-my-blog-post-title.md`. The post date is extracted from the file name.
@ -51,7 +51,7 @@ This is my first post on Docusaurus 2.
A whole bunch of exploration to follow. A whole bunch of exploration to follow.
``` ```
## Header options ## Header options {#header-options}
The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options. The only required field is `title`; however, we provide options to add author information to your blog post as well along with other options.
@ -66,7 +66,7 @@ The only required field is `title`; however, we provide options to add author in
- `image`: Cover or thumbnail image that will be used when displaying the link to your post. - `image`: Cover or thumbnail image that will be used when displaying the link to your post.
- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`. - `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`.
## Summary truncation ## Summary truncation {#summary-truncation}
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: 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:
@ -87,7 +87,7 @@ Not this.
Or this. Or this.
``` ```
## Feed ## Feed {#feed}
You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`. You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set `feedOptions.type` to `null`.
@ -136,9 +136,9 @@ and for Atom:
https://{your-domain}/blog/atom.xml https://{your-domain}/blog/atom.xml
``` ```
## Advanced topics ## Advanced topics {#advanced-topics}
### Blog-only mode ### Blog-only mode {#blog-only-mode}
You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path. You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to indicate it's the root path.
@ -185,7 +185,7 @@ module.exports = {
}; };
``` ```
### Multiple blogs ### Multiple blogs {#multiple-blogs}
By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`. By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! You can add another blog by specifying another blog plugin in the `plugins` option for `docusaurus.config.js`.

30
website/versioned_docs/version-2.0.0-alpha.71/cli.md
View file

@ -24,21 +24,21 @@ Once your website is bootstrapped, the website source will contain the Docusauru
} }
``` ```
## Index ## Index {#index}
import TOCInline from "@theme/TOCInline" import TOCInline from "@theme/TOCInline"
<TOCInline toc={toc[1].children}/> <TOCInline toc={toc[1].children}/>
## Docusaurus CLI commands ## Docusaurus CLI commands {#docusaurus-cli-commands}
Below is a list of Docusaurus CLI commands and their usages: Below is a list of Docusaurus CLI commands and their usages:
### `docusaurus start [siteDir]` ### `docusaurus start [siteDir]` {#docusaurus-start-sitedir}
Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server). Builds and serves a preview of your site locally with [Webpack Dev Server](https://webpack.js.org/configuration/dev-server).
#### Options #### Options {#options}
| Name | Default | Description | | Name | Default | Description |
| --- | --- | --- | | --- | --- | --- |
@ -55,7 +55,7 @@ Please note that some functionality (for example, anchor links) will not work in
::: :::
#### Enabling HTTPS` #### Enabling HTTPS` {#enabling-https}
There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example. There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example.
@ -71,11 +71,11 @@ HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start
4. Open `https://localhost:3000/` 4. Open `https://localhost:3000/`
### `docusaurus build [siteDir]` ### `docusaurus build [siteDir]` {#docusaurus-build-sitedir}
Compiles your site for production. Compiles your site for production.
#### Options #### Options {#options-1}
| Name | Default | Description | | Name | Default | Description |
| --- | --- | --- | | --- | --- | --- |
@ -90,7 +90,7 @@ For advanced minification of CSS bundle, we use the [advanced cssnano preset](ht
::: :::
### `docusaurus swizzle [siteDir]` ### `docusaurus swizzle [siteDir]` {#docusaurus-swizzle-sitedir}
:::caution :::caution
@ -111,7 +111,7 @@ Running the command will copy the relevant theme files to your site folder. You
`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 {#options-2}
| Name | Description | | Name | Description |
| ------------------ | -------------------------------------- | | ------------------ | -------------------------------------- |
@ -139,11 +139,11 @@ TODO a separate section for swizzle tutorial.
To learn more about swizzling, check [here](#). To learn more about swizzling, check [here](#).
--> -->
### `docusaurus deploy [siteDir]` ### `docusaurus deploy [siteDir]` {#docusaurus-deploy-sitedir}
Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.mdx#deploying-to-github-pages) for more details. Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.mdx#deploying-to-github-pages) for more details.
#### Options #### Options {#options-3}
| Name | Default | Description | | Name | Default | Description |
| --- | --- | --- | | --- | --- | --- |
@ -151,7 +151,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the
| `--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 custom deploy script. |
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
### `docusaurus serve [siteDir]` ### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
Serve your built website locally. Serve your built website locally.
@ -163,13 +163,13 @@ Serve your built website locally.
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
| `--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`. | | `--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`. |
### `docusaurus clear [siteDir]` ### `docusaurus clear [siteDir]` {#docusaurus-clear-sitedir}
Clear a Docusaurus site's generated assets, caches, build artifacts. Clear a Docusaurus site's generated assets, caches, build artifacts.
We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site. We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.
### `docusaurus write-translations [siteDir]` ### `docusaurus write-translations [siteDir]` {#docusaurus-write-translations-sitedir}
Write the JSON translation files that you will have to translate. Write the JSON translation files that you will have to translate.
@ -182,6 +182,6 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` | | `--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 to add a prefix to each translation message, to help you highlight untranslated strings |
### `docusaurus write-heading-ids [siteDir]` ### `docusaurus write-heading-ids [siteDir]` {#docusaurus-write-heading-ids-sitedir}
Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site. Add [explicit heading ids](./guides/markdown-features/markdown-features-headings.mdx#explicit-ids) to the Markdown documents of your site.

14
website/versioned_docs/version-2.0.0-alpha.71/configuration.md
View file

@ -9,7 +9,7 @@ Docusaurus has a unique take on configurations. We encourage you to congregate i
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 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 `docusaurus.config.js`? {#what-goes-into-a-docusaurusconfigjs}
You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options. You should not have to write your `docusaurus.config.js` from scratch even if you are developing your site. All templates come with a `docusaurus.config.js` that includes defaults for the common options.
@ -21,19 +21,19 @@ The high-level overview of Docusaurus configuration can be categorized into:
For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md). For exact reference to each of the configurable fields, you may refer to [**`docusaurus.config.js` API reference**](api/docusaurus.config.js.md).
### Site metadata ### 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 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.
### Deployment configurations ### Deployment configurations {#deployment-configurations}
Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command. Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with the `deploy` command.
It is recommended to check the [deployment docs](deployment.mdx) for more information. It is recommended to check the [deployment docs](deployment.mdx) for more information.
### Theme, plugin, and preset configurations ### Theme, plugin, and preset configurations {#theme-plugin-and-preset-configurations}
List the [theme](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages: List the [theme](using-themes.md), [plugins](using-plugins.md), and [presets](presets.md) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages:
@ -102,7 +102,7 @@ module.exports = {
For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md). For further help configuring themes, plugins, and presets, see [Using Themes](using-themes.md), [Using Plugins](using-plugins.md), and [Using Presets](presets.md).
### Custom configurations ### Custom configurations {#custom-configurations}
Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`. Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fields, define them in `customFields`.
@ -121,7 +121,7 @@ module.exports = {
}; };
``` ```
## Accessing configuration from components ## Accessing configuration from components {#accessing-configuration-from-components}
Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`. Your configuration object will be made available to all the components of your site. And you may access them via React context as `siteConfig`.
@ -148,7 +148,7 @@ If you just want to use those fields on the client side, you could create your o
::: :::
## Customizing Babel Configuration ## 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 project root.

48
website/versioned_docs/version-2.0.0-alpha.71/contributing.md
View file

@ -10,11 +10,11 @@ The [Open Source Guides](https://opensource.guide/) website has a collection of
- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/) - [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
- [Building Welcoming Communities](https://opensource.guide/building-community/) - [Building Welcoming Communities](https://opensource.guide/building-community/)
## [Code of Conduct](https://code.fb.com/codeofconduct) ## [Code of Conduct](https://code.fb.com/codeofconduct) {#code-of-conduct}
Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated. Facebook has adopted a Code of Conduct that we expect project participants to adhere to. Please read [the full text](https://code.fb.com/codeofconduct) so that you can understand what actions will and will not be tolerated.
## Get involved ## Get involved {#get-involved}
There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started: There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started:
@ -25,24 +25,24 @@ There are many ways to contribute to Docusaurus, and many of them do not involve
Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help. Contributions are very welcome. If you think you need help planning your contribution, please ping us on Twitter at [@docusaurus](https://twitter.com/docusaurus) and let us know you are looking for a bit of help.
### Join our Discord channel ### Join our Discord channel {#join-our-discord-channel}
To participate in Docusaurus 2 dev, join the [#docusaurus-2-dev](https://discord.gg/Je6Ash6) channel. To participate in Docusaurus 2 dev, join the [#docusaurus-2-dev](https://discord.gg/Je6Ash6) channel.
## Our development process ## Our development process {#our-development-process}
Docusaurus uses [GitHub](https://github.com/facebook/docusaurus) as its source of truth. The core team will be working directly there. All changes will be public from the beginning. Docusaurus uses [GitHub](https://github.com/facebook/docusaurus) as its source of truth. The core team will be working directly there. All changes will be public from the beginning.
When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI. When a change made on GitHub is approved, it will be checked by our continuous integration system, CircleCI.
### Reporting new issues ### Reporting new issues {#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 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. - **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. - **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.
### Reporting bugs ### Reporting bugs {#reporting-bugs}
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 a are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues). 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 a are certain this is a new, unreported bug, you can submit a [bug report](#reporting-new-issues).
@ -50,19 +50,19 @@ If you have questions about using Docusaurus, contact the Docusaurus Twitter acc
You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md/) You can also file issues as [feature requests or enhancements](https://github.com/facebook/docusaurus/labels/feature). If you see anything you'd like to be implemented, create an issue with [feature template](https://raw.githubusercontent.com/facebook/docusaurus/master/.github/ISSUE_TEMPLATE/feature.md/)
### Reporting security bugs ### Reporting security bugs {#reporting-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. 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.
## Working on Docusaurus code ## Working on Docusaurus code {#working-on-docusaurus-code}
### Installation ### Installation {#installation}
1. Ensure you have [Yarn](https://yarnpkg.com/) installed 1. Ensure you have [Yarn](https://yarnpkg.com/) installed
2. After cloning the repository, run `yarn install` in the root of the repository 2. After cloning the repository, run `yarn install` in the root of the repository
3. To start a local development server serving the Docusaurus docs, go into the `website` directory and run `yarn start` 3. To start a local development server serving the Docusaurus docs, go into the `website` directory and run `yarn start`
### Semantic commit messages ### Semantic commit messages {#semantic-commit-messages}
See how a minor change to your commit message style can make you a better programmer. See how a minor change to your commit message style can make you a better programmer.
@ -93,26 +93,26 @@ The various types of commits:
Use lower case not title case! Use lower case not title case!
### Code conventions ### Code conventions {#code-conventions}
#### Style guide #### Style guide {#style-guide}
[Prettier](https://prettier.io/) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`. [Prettier](https://prettier.io/) will catch most styling issues that may exist in your code. You can check the status of your code styling by simply running `npm run prettier`.
However, there are still some styles that Prettier cannot pick up. However, there are still some styles that Prettier cannot pick up.
#### General #### General {#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.
- "Attractive" - "Attractive"
#### Documentation #### Documentation {#documentation}
- Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation. - Do not wrap lines at 80 characters - configure your editor to soft-wrap when editing documentation.
## Pull requests ## Pull requests {#pull-requests}
### Your first pull request ### Your first pull request {#your-first-pull-request}
So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at. So you have decided to contribute code back to upstream by opening a pull request. You've invested a good chunk of time, and we appreciate it. We will do our best to work with you and get the PR looked at.
@ -122,7 +122,7 @@ Working on your first Pull Request? You can learn how from this free video serie
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.
### Proposing a change ### Proposing a change {#proposing-a-change}
If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md/). If you would like to request a new feature or enhancement but are not yet thinking about opening a pull request, you can also file an issue with [feature template](https://github.com/facebook/docusaurus/issues/new?template=feature.md/).
@ -130,7 +130,7 @@ If you intend to change the public API (e.g., something in `docusaurus.config.js
If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue. If you're only fixing a bug, it's fine to submit a pull request right away but we still recommend to file an issue detailing what you're fixing. This is helpful in case we don't accept that specific fix but want to keep track of the issue.
### Sending a pull request ### Sending a pull request {#sending-a-pull-request}
Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this [commit message style](#semantic-commit-messages). Small pull requests are much easier to review and more likely to get merged. Make sure the PR does only one thing, otherwise please split it. It is recommended to follow this [commit message style](#semantic-commit-messages).
@ -145,13 +145,13 @@ Please make sure the following is done when submitting a pull request:
All pull requests should be opened against the `master` branch. All pull requests should be opened against the `master` branch.
#### Test plan #### Test plan {#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, 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.
#### Breaking changes #### Breaking changes {#breaking-changes}
When adding a new breaking change, follow this template in your pull request: When adding a new breaking change, follow this template in your pull request:
@ -164,7 +164,7 @@ When adding a new breaking change, follow this template in your pull request:
- **Severity (number of people affected x effort)**: - **Severity (number of people affected x effort)**:
``` ```
#### Copyright header for source code #### Copyright header for source code {#copyright-header-for-source-code}
Copy and paste this to the top of your new file(s): Copy and paste this to the top of your new file(s):
@ -177,14 +177,14 @@ Copy and paste this to the top of your new file(s):
*/ */
``` ```
#### Contributor License Agreement (CLA) #### Contributor License Agreement (CLA) {#contributor-license-agreement-cla}
In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla). In order to accept your pull request, we need you to submit a CLA. You only need to do this once, so if you've done this for another Facebook open source project, you're good to go. If you are submitting a pull request for the first time, the Facebook GitHub Bot will reply with a link to the CLA form. You may also [complete your CLA here](https://code.facebook.com/cla).
### What happens next? ### What happens next? {#what-happens-next}
The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above. The core Docusaurus team will be monitoring for pull requests. Do help us by keeping pull requests consistent by following the guidelines above.
## License ## License {#license}
By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license. By contributing to Docusaurus, you agree that your contributions will be licensed under its MIT license.

32
website/versioned_docs/version-2.0.0-alpha.71/deployment.mdx
View file

@ -13,7 +13,7 @@ Once it finishes, the static files will be generated within the `build/` directo
You can deploy your site to static site hosting services such as [Vercel](https://vercel.com/), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/docs/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too! You can deploy your site to static site hosting services such as [Vercel](https://vercel.com/), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/docs/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too!
## Testing Build Local ## Testing Build Local {#testing-build-local}
It is important to test build before deploying to a production. Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve) command to test build locally. It is important to test build before deploying to a production. Docusaurus includes a [`docusaurus serve`](cli.md#docusaurus-serve) command to test build locally.
@ -21,7 +21,7 @@ It is important to test build before deploying to a production. Docusaurus inclu
npm run serve npm run serve
``` ```
## Self Hosting ## Self Hosting {#self-hosting}
:::warning :::warning
@ -35,11 +35,11 @@ Docusaurus can be self hosted using [`docusaurus serve`](cli.md#docusaurus-serve
npm run serve -- --build --port 80 --host 0.0.0.0 npm run serve -- --build --port 80 --host 0.0.0.0
``` ```
## Deploying to GitHub Pages ## Deploying to GitHub Pages {#deploying-to-github-pages}
Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository. Docusaurus provides an easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository.
### `docusaurus.config.js` settings ### `docusaurus.config.js` settings {#docusaurusconfigjs-settings}
First, modify your `docusaurus.config.js` and add the required params: First, modify your `docusaurus.config.js` and add the required params:
@ -77,7 +77,7 @@ By default, GitHub Pages runs published files through [Jekyll](https://jekyllrb.
::: :::
### Environment settings ### Environment settings {#environment-settings}
Specify the Git user as an environment variable. Specify the Git user as an environment variable.
@ -100,7 +100,7 @@ GitHub enterprise installations should work in the same manner as github.com; yo
| ------------- | ----------------------------------------------- | | ------------- | ----------------------------------------------- |
| `GITHUB_HOST` | The domain name of your GitHub enterprise site. | | `GITHUB_HOST` | The domain name of your GitHub enterprise site. |
### Deploy ### Deploy {#deploy}
Finally, to deploy your site to GitHub Pages, run: Finally, to deploy your site to GitHub Pages, run:
@ -136,7 +136,7 @@ cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
</Tabs> </Tabs>
```` ````
### Triggering deployment with GitHub Actions ### Triggering deployment with GitHub Actions {#triggering-deployment-with-github-actions}
[GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository. [GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
@ -209,7 +209,7 @@ jobs:
1. When pull request is merged to `documentation` branch or someone pushes to `documentation` branch directly it will be built and deployed to `gh-pages` branch. 1. When pull request is merged to `documentation` branch or someone pushes to `documentation` branch directly it will be built and deployed to `gh-pages` branch.
1. After this step, your updated documentation will be available on the GitHub pages. 1. After this step, your updated documentation will be available on the GitHub pages.
### Triggering deployment with Travis CI ### Triggering deployment with Travis CI {#triggering-deployment-with-travis-ci}
Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider. Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate the deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider.
@ -237,7 +237,7 @@ script:
Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script. Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
### Using Azure Pipelines ### Using Azure Pipelines {#using-azure-pipelines}
1. Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already. 1. Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already.
1. Create an organization and within the organization create a project and connect your repository from GitHub. 1. Create an organization and within the organization create a project and connect your repository from GitHub.
@ -273,7 +273,7 @@ steps:
displayName: 'yarn install and build' displayName: 'yarn install and build'
``` ```
### Using Drone ### Using Drone {#using-drone}
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. 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.
1. 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). 1. 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).
@ -307,7 +307,7 @@ trigger:
Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website. Now, whenever you push a new tag to github, this trigger will start the drone ci job to publish your website.
## Deploying to Netlify ## Deploying to Netlify {#deploying-to-netlify}
To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured: To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
@ -336,7 +336,7 @@ Make sure to disable Netlify setting `Pretty URLs` to prevent lowercased URLs, u
::: :::
## Deploying to Vercel ## Deploying to Vercel {#deploying-to-vercel}
Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use. Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use.
@ -346,11 +346,11 @@ Import the project into Vercel using the [Import Flow](https://vercel.com/import
After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production). After your project has been imported, all subsequent pushes to branches will generate [Preview Deployments](https://vercel.com/docs/platform/deployments#preview), and all changes made to the [Production Branch](https://vercel.com/docs/git-integrations#production-branch) (commonly "main") will result in a [Production Deployment](https://vercel.com/docs/platform/deployments#production).
## Deploying to Render ## 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 Surge ## Deploying to Surge {#deploying-to-surge}
Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL). Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from the command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL).
@ -378,7 +378,7 @@ First-time users of Surge would be prompted to create an account from the comman
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). 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).
### Using your domain ### Using your domain {#using-your-domain}
If you have a domain name you can deploy your site using surge to your domain using the command: If you have a domain name you can deploy your site using surge to your domain using the command:
@ -388,7 +388,7 @@ surge build/ yourdomain.com
Your site is now deployed for free at `subdomain.surge.sh` or `yourdomain.com` depending on the method you chose. Your site is now deployed for free at `subdomain.surge.sh` or `yourdomain.com` depending on the method you chose.
### Setting up CNAME file ### Setting up CNAME file {#setting-up-cname-file}
Store your domain in a CNAME file for future deployments with the following command: Store your domain in a CNAME file for future deployments with the following command:

2
website/versioned_docs/version-2.0.0-alpha.71/design-principles.md
View file

@ -15,7 +15,7 @@ This section is a work in progress.
- **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them. - **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. - **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.
## How Docusaurus works ## How Docusaurus works {#how-docusaurus-works}
<!-- moved in from how Docusaurus works @yangshun --> <!-- moved in from how Docusaurus works @yangshun -->

60
website/versioned_docs/version-2.0.0-alpha.71/docusaurus-core.md
View file

@ -6,9 +6,9 @@ sidebar_label: Client API
Docusaurus provides some APIs on the clients that can be helpful to you when building your site. Docusaurus provides some APIs on the clients that can be helpful to you when building your site.
## Components ## Components {#components}
### `<Head/>` ### `<Head/>` {#head}
This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around [React Helmet](https://github.com/nfl/react-helmet). This reusable React component will manage all of your changes to the document head. It takes plain HTML tags and outputs plain HTML tags and is beginner-friendly. It is a wrapper around [React Helmet](https://github.com/nfl/react-helmet).
@ -54,7 +54,7 @@ Outputs:
</head> </head>
``` ```
### `<Link/>` ### `<Link/>` {#link}
This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an `IntersectionObserver` to fetch a low-priority request when the `<Link>` is in the viewport and then use an `onMouseOver` event to trigger a high-priority request when it is likely that a user will navigate to the requested resource. This component enables linking to internal pages as well as a powerful performance feature called preloading. Preloading is used to prefetch resources so that the resources are fetched by the time the user navigates with this component. We use an `IntersectionObserver` to fetch a low-priority request when the `<Link>` is in the viewport and then use an `onMouseOver` event to trigger a high-priority request when it is likely that a user will navigate to the requested resource.
@ -77,7 +77,7 @@ const Page = () => (
); );
``` ```
#### `to`: string #### `to`: string {#to-string}
The target location to navigate to. Example: `/docs/introduction`. The target location to navigate to. Example: `/docs/introduction`.
@ -85,7 +85,7 @@ The target location to navigate to. Example: `/docs/introduction`.
<Link to="/courses" /> <Link to="/courses" />
``` ```
### `<Redirect/>` ### `<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.
@ -106,7 +106,7 @@ const Home = () => {
::: :::
### `<BrowserOnly/>` ### `<BrowserOnly/>` {#browseronly}
The `<BrowserOnly>` component accepts a `children` prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the `window`/`document` objects are being accessed). To improve SEO, you can also provide fallback content using the `fallback` prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser. The `<BrowserOnly>` component accepts a `children` prop, a render function which will not be executed during the pre-rendering phase of the build process. This is useful for hiding code that is only meant to run in the browsers (e.g. where the `window`/`document` objects are being accessed). To improve SEO, you can also provide fallback content using the `fallback` prop, which will be prerendered until in the build process and replaced with the client-side only contents when viewed in the browser.
@ -125,13 +125,13 @@ const MyComponent = () => {
}; };
``` ```
### `<Interpolate/>` ### `<Interpolate/>` {#interpolate}
A simple interpolation component for text containing dynamic placeholders. A simple interpolation component for text containing dynamic placeholders.
The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...). The placeholders will be replaced with the provided dynamic values and JSX elements of your choice (strings, links, styled elements...).
#### Props #### Props {#props}
- `children`: text containing interpolation placeholders like `{placeholderName}` - `children`: text containing interpolation placeholders like `{placeholderName}`
- `values`: object containing interpolation placeholder values - `values`: object containing interpolation placeholder values
@ -160,7 +160,7 @@ export default function VisitMyWebsiteMessage() {
} }
``` ```
### `<Translate/>` ### `<Translate/>` {#translate}
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). 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).
@ -174,14 +174,14 @@ Apart the `values` prop used for interpolation, it is **not possible to use vari
::: :::
#### Props #### Props {#props-1}
- `children`: untranslated string in the default site locale (can contain [interpolation placeholders](#interpolate)) - `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 use as key in JSON translation files
- `description`: optional text to help the translator - `description`: optional text to help the translator
- `values`: optional object containing interpolation placeholder values - `values`: optional object containing interpolation placeholder values
#### Example #### Example {#example}
```jsx title="src/index.js" ```jsx title="src/index.js"
import React from 'react'; import React from 'react';
@ -215,9 +215,9 @@ export default function Home() {
} }
``` ```
## Hooks ## Hooks {#hooks}
### `useDocusaurusContext` ### `useDocusaurusContext` {#usedocusauruscontext}
React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md), and some additional site metadata. React hook to access Docusaurus Context. Context contains `siteConfig` object from [docusaurus.config.js](api/docusaurus.config.js.md), and some additional site metadata.
@ -258,7 +258,7 @@ const MyComponent = () => {
}; };
``` ```
### `useBaseUrl` ### `useBaseUrl` {#usebaseurl}
React hook to prepend your site `baseUrl` to a string. React hook to prepend your site `baseUrl` to a string.
@ -273,7 +273,7 @@ The `/baseUrl/` prefix is automatically added to all **absolute paths** by defau
::: :::
#### Options #### Options {#options}
```ts ```ts
type BaseUrlOptions = { type BaseUrlOptions = {
@ -282,7 +282,7 @@ type BaseUrlOptions = {
}; };
``` ```
#### Example usage: #### Example usage: {#example-usage}
```jsx ```jsx
import React from 'react'; import React from 'react';
@ -308,7 +308,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
::: :::
### `useBaseUrlUtils` ### `useBaseUrlUtils` {#usebaseurlutils}
Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url. Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
@ -328,7 +328,7 @@ const Component = () => {
}; };
``` ```
### `useGlobalData` ### `useGlobalData` {#useglobaldata}
React hook to access Docusaurus global data created by all the plugins. React hook to access Docusaurus global data created by all the plugins.
@ -369,7 +369,7 @@ Inspect your site's global data at `./docusaurus/globalData.json`
::: :::
### `usePluginData` ### `usePluginData` {#useplugindata}
Access global data created by a specific plugin instance. Access global data created by a specific plugin instance.
@ -393,7 +393,7 @@ const MyComponent = () => {
}; };
``` ```
### `useAllPluginInstancesData` ### `useAllPluginInstancesData` {#useallplugininstancesdata}
Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id. Access global data created by a specific plugin. Given a plugin name, it returns the data of all the plugins instances of that name, by plugin id.
@ -414,13 +414,13 @@ const MyComponent = () => {
}; };
``` ```
## Functions ## Functions {#functions}
### `interpolate` ### `interpolate` {#interpolate-1}
The imperative counterpart of the [`<Interpolate>`](#interpolate) component. The imperative counterpart of the [`<Interpolate>`](#interpolate) component.
#### Signature #### Signature {#signature}
```ts ```ts
// Simple string interpolation // Simple string interpolation
@ -433,7 +433,7 @@ function interpolate(
): ReactNode; ): ReactNode;
``` ```
#### Example #### Example {#example-1}
```jsx ```jsx
// highlight-start // highlight-start
@ -443,7 +443,7 @@ import {interpolate} from '@docusaurus/Interpolate';
const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'}); const message = interpolate('Welcome {firstName}', {firstName: 'Sébastien'});
``` ```
### `translate` ### `translate` {#translate-1}
The imperative counterpart of the [`<Translate>`](#translate) component. Also supporting [placeholders interpolation](#interpolate). The imperative counterpart of the [`<Translate>`](#translate) component. Also supporting [placeholders interpolation](#interpolate).
@ -457,7 +457,7 @@ Use the imperative API for the **rare cases** where a **component cannot be used
::: :::
#### Signature #### Signature {#signature-1}
```ts ```ts
function translate( function translate(
@ -466,7 +466,7 @@ function translate(
): string; ): string;
``` ```
#### Example #### Example {#example-2}
```jsx title="src/index.js" ```jsx title="src/index.js"
import React from 'react'; import React from 'react';
@ -504,9 +504,9 @@ export default function Home() {
} }
``` ```
## Modules ## Modules {#modules}
### `ExecutionEnvironment` ### `ExecutionEnvironment` {#executionenvironment}
A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code. A module which exposes a few boolean variables to check the current rendering environment. Useful if you want to only run certain code on client/server or need to write server-side rendering compatible code.
@ -527,7 +527,7 @@ const MyPage = () => {
| `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. | | `ExecutionEnvironment.canUseIntersectionObserver` | `true` if on client and has `IntersectionObserver`. |
| `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. | | `ExecutionEnvironment.canUseViewport` | `true` if on client and has `window.screen`. |
### `constants` ### `constants` {#constants}
A module exposing useful constants to client-side theme code. A module exposing useful constants to client-side theme code.

10
website/versioned_docs/version-2.0.0-alpha.71/guides/creating-pages.md
View file

@ -10,7 +10,7 @@ The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
You can use React components, or Markdown. You can use React components, or Markdown.
## Add a React page ## Add a React page {#add-a-react-page}
Create a file `/src/pages/helloReact.js`: Create a file `/src/pages/helloReact.js`:
@ -50,7 +50,7 @@ You can also create TypeScript pages with the `.tsx` extension (`helloReact.tsx`
::: :::
## Add a Markdown page ## Add a Markdown page {#add-a-markdown-page}
Create a file `/src/pages/helloMarkdown.md`: Create a file `/src/pages/helloMarkdown.md`:
@ -78,7 +78,7 @@ You can use the full power of React in Markdown pages too, refer to the [MDX](ht
::: :::
## Routing ## Routing {#routing}
If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example: If you are familiar with other static site generators like Jekyll and Next, this routing approach will feel familiar to you. Any JavaScript file you create under `/src/pages/` directory will be automatically converted to a website page, following the `/src/pages/` directory hierarchy. For example:
@ -113,10 +113,10 @@ All JavaScript/TypeScript files within the `src/pages/` directory will have corr
::: :::
## Using React ## 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. 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}
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. 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.

6
website/versioned_docs/version-2.0.0-alpha.71/guides/docs/docs-introduction.md
View file

@ -7,7 +7,7 @@ slug: /docs-introduction
The docs feature provides users with a way to organize Markdown files in a hierarchical format. The docs feature provides users with a way to organize Markdown files in a hierarchical format.
## Document ID ## Document ID {#document-id}
Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory. Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
@ -49,7 +49,7 @@ It is possible to use:
::: :::
## Home page docs ## Home page docs {#home-page-docs}
If you want a document to be available at the root, and have a path like `https://v2.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://v2.docusaurus.io/docs/`, you can use the slug frontmatter:
@ -61,7 +61,7 @@ slug: /
Lorem ipsum Lorem ipsum
``` ```
## Docs-only mode ## Docs-only mode {#docs-only-mode}
If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead. If you only want the documentation feature, you can run your Docusaurus 2 site without a landing page and display your documentation page as the index page instead.

4
website/versioned_docs/version-2.0.0-alpha.71/guides/docs/docs-markdown-features.mdx
View file

@ -7,11 +7,11 @@ 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-frontmatter}
Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter) Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
## Referencing other documents ## Referencing other documents {#referencing-other-documents}
If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`). If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).

14
website/versioned_docs/version-2.0.0-alpha.71/guides/docs/docs-multi-instance.mdx
View file

@ -13,13 +13,13 @@ This feature is only useful for [versioned documentations](./versioning.md). It
::: :::
## Use-cases ## Use-cases {#use-cases}
Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more). Sometimes you want a Docusaurus site to host 2 distinct sets of documentation (or more).
These documentations may even have different versioning/release lifecycles. These documentations may even have different versioning/release lifecycles.
### Mobile SDKs documentation ### Mobile SDKs documentation {#mobile-sdks-documentation}
If you build a cross-platform mobile SDK, you may have 2 documentations: If you build a cross-platform mobile SDK, you may have 2 documentations:
@ -36,7 +36,7 @@ If someone edits the iOS documentation, is it really useful to rebuild everythin
::: :::
### Versioned and unversioned doc ### Versioned and unversioned doc {#versioned-and-unversioned-doc}
Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them. Sometimes, you want some documents to be versioned, while other documents are more "global", and it feels useless to version them.
@ -45,7 +45,7 @@ We use this pattern on the Docusaurus website itself:
- The [/docs/\*](/docs) section is versioned - The [/docs/\*](/docs) section is versioned
- The [/community/\*](/community/support) section is unversioned - The [/community/\*](/community/support) section is unversioned
## Setup ## Setup {#setup}
Let's consider we 2 documentations: Let's consider we 2 documentations:
@ -138,7 +138,7 @@ We consider that the `product` instance is the most important one, and make it t
::: :::
## Versioned paths ## Versioned paths {#versioned-paths}
Each instance will store versioned docs in a distinct folder. Each instance will store versioned docs in a distinct folder.
@ -162,7 +162,7 @@ The instance paths will be simpler, and retro-compatible with a single-instance
::: :::
## Tagging new versions ## Tagging new versions {#tagging-new-versions}
Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run: Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run:
@ -182,7 +182,7 @@ To version the non-default/community docs plugin instance:
npm run docusaurus docs:version:community 1.0.0 npm run docusaurus docs:version:community 1.0.0
``` ```
## Docs navbar items ## Docs navbar items {#docs-navbar-items}
Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute. Each docs-related [theme navbar items](../../api/themes/theme-configuration.md#navbar) take an optional `docsPluginId` attribute.

22
website/versioned_docs/version-2.0.0-alpha.71/guides/docs/sidebar.md
View file

@ -27,7 +27,7 @@ module.exports = {
}; };
``` ```
## Sidebar object ## Sidebar object {#sidebar-object}
A sidebar object contains [sidebar items](#understanding-sidebar-items) and it is defined like this: A sidebar object contains [sidebar items](#understanding-sidebar-items) and it is defined like this:
@ -83,7 +83,7 @@ Shorthand notation relies on the iteration order of JavaScript object keys for t
::: :::
## Using multiple sidebars ## Using multiple sidebars {#using-multiple-sidebars}
You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object. You can have multiple sidebars for different Markdown files by adding more top-level keys to the exported object.
@ -107,7 +107,7 @@ For example, with the above example, when displaying the `doc2` page, the sideba
For more information about sidebars and how they relate to doc pages, see [Navbar doc link](../../api/themes/theme-configuration.md#navbar-doc-link). For more information about sidebars and how they relate to doc pages, see [Navbar doc link](../../api/themes/theme-configuration.md#navbar-doc-link).
## Understanding sidebar items ## Understanding sidebar items {#understanding-sidebar-items}
As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarItem as a `type` that defines what the item links to. As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarItem as a `type` that defines what the item links to.
@ -118,7 +118,7 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. A SidebarIte
- [Ref](#creating-a-link-to-page-without-sidebar) - [Ref](#creating-a-link-to-page-without-sidebar)
- [Category](#creating-a-hierarchy) - [Category](#creating-a-hierarchy)
### Linking to a doc page ### Linking to a doc page {#linking-to-a-doc-page}
Set `type` to `doc` to link to a documentation page. This is the default type. Set `type` to `doc` to link to a documentation page. This is the default type.
@ -163,7 +163,7 @@ module.exports = {
}; };
``` ```
### Creating a generic link ### Creating a generic link {#creating-a-generic-link}
Set `type` to `link` to link to a non-documentation page. For example, to create an external link. Set `type` to `link` to link to a non-documentation page. For example, to create an external link.
@ -185,7 +185,7 @@ Example:
} }
``` ```
### Creating a link to page without sidebar ### Creating a link to page without sidebar {#creating-a-link-to-page-without-sidebar}
Set `type` to `ref` to link to a documentation page without binding it to a sidebar. This means the sidebar disappears when the user displays the linked page. Set `type` to `ref` to link to a documentation page without binding it to a sidebar. This means the sidebar disappears when the user displays the linked page.
@ -205,7 +205,7 @@ Example:
} }
``` ```
### Creating a hierarchy ### Creating a hierarchy {#creating-a-hierarchy}
The Sidebar item type that creates a hierarchy in the sidebar. Set `type` to `category`. The Sidebar item type that creates a hierarchy in the sidebar. Set `type` to `category`.
@ -260,7 +260,7 @@ module.exports = {
}; };
``` ```
#### Collapsible categories #### Collapsible categories {#collapsible-categories}
For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`: For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`:
@ -274,7 +274,7 @@ module.exports = {
}; };
``` ```
#### Expanded categories by default #### Expanded categories by default {#expanded-categories-by-default}
For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`: For docs that have collapsible categories, you may want more fine-grain control over certain categories. If you want specific categories to be always expanded, you can set `collapsed` to `false`:
@ -294,7 +294,7 @@ module.exports = {
}; };
``` ```
## Hideable sidebar ## Hideable sidebar {#hideable-sidebar}
Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets). Using the enabled `themeConfig.hideableSidebar` option, you can make the entire sidebar hidden, allowing you to better focus your users on the content. This is especially useful when content consumption on medium screens (e.g. on tablets).
@ -308,7 +308,7 @@ module.exports = {
}; };
``` ```
## Passing custom props ## Passing custom props {#passing-custom-props}
To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items: To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:

28
website/versioned_docs/version-2.0.0-alpha.71/guides/docs/versioning.md
View file

@ -16,7 +16,7 @@ Most of the time, you don't need versioning as it will just increase your build
To better understand how versioning works and see if it suits your needs, you can read on below. To better understand how versioning works and see if it suits your needs, you can read on below.
## Directory structure ## Directory structure {#directory-structure}
```shell ```shell
website website
@ -50,7 +50,7 @@ The table below explains how a versioned file maps to its version and the genera
| `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello | | `versioned_docs/version-1.1.0/hello.md` | 1.1.0 (latest) | /docs/hello |
| `docs/hello.md` | next | /docs/next/hello | | `docs/hello.md` | next | /docs/next/hello |
### Tagging a new version ### Tagging a new version {#tagging-a-new-version}
1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master. 1. First, make sure your content in the `docs` directory is ready to be frozen as a version. A version always should be based from master.
1. Enter a new version number. 1. Enter a new version number.
@ -65,9 +65,9 @@ When tagging a new version, the document versioning mechanism will:
- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`. - Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
- Append the new version number to `versions.json`. - Append the new version number to `versions.json`.
## Docs ## Docs {#docs}
### Creating new docs ### Creating new docs {#creating-new-docs}
1. Place the new file into the corresponding version folder. 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. 1. Include the reference for the new file into the corresponding sidebar file, according to version number.
@ -92,7 +92,7 @@ versioned_docs/version-1.0.0/new.md
versioned_sidebars/version-1.0.0-sidebars.json versioned_sidebars/version-1.0.0-sidebars.json
``` ```
### Linking docs ### Linking docs {#linking-docs}
- Remember to include the `.md` extension. - Remember to include the `.md` extension.
- Files will be linked to correct corresponding version. - Files will be linked to correct corresponding version.
@ -104,11 +104,11 @@ The [@hello](hello.md#paginate) document is great!
See the [Tutorial](../getting-started/tutorial.md) for more info. See the [Tutorial](../getting-started/tutorial.md) for more info.
``` ```
## Versions ## Versions {#versions}
Each directory in `versioned_docs/` will represent a documentation version. Each directory in `versioned_docs/` will represent a documentation version.
### Updating an existing version ### Updating an existing version {#updating-an-existing-version}
You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published. You can update multiple docs versions at the same time because each directory in `versioned_docs/` represents specific routes when published.
@ -118,7 +118,7 @@ You can update multiple docs versions at the same time because each directory in
Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`. Example: When you change any file in `versioned_docs/version-2.6/`, it will only affect the docs for version `2.6`.
### Deleting an existing version ### Deleting an existing version {#deleting-an-existing-version}
You can delete/remove versions as well. You can delete/remove versions as well.
@ -137,9 +137,9 @@ Example:
2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`. 2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`.
3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`. 3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`.
## Recommended practices ## Recommended practices {#recommended-practices}
### Figure out the behavior for the "current" version ### Figure out the behavior for the "current" version {#figure-out-the-behavior-for-the-current-version}
The "current" version is the version name for the `./docs` folder. The "current" version is the version name for the `./docs` folder.
@ -168,17 +168,17 @@ The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, an
See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details. See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details.
### Version your documentation only when needed ### Version your documentation only when needed {#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 a documentation for your npm package `foo` and you are currently in version 1.0.0. You then release a patch version for a minor bug fix and it's now 1.0.1.
Should you cut a new documentation version 1.0.1? **You probably shouldn't**. 1.0.1 and 1.0.0 docs shouldn't differ according to semver because there are no new features!. Cutting a new version for it will only just create unnecessary duplicated files. 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 {#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 version 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. **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 version with the lowest being `22.X`. Keep it small 😊
### Use absolute import within the docs ### 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:
@ -187,7 +187,7 @@ Don't use relative paths import within the docs. Because when we cut a version t
+ import Foo from '@site/src/components/Foo'; + import Foo from '@site/src/components/Foo';
``` ```
### Global or versioned colocated assets ### 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

2
website/versioned_docs/version-2.0.0-alpha.71/guides/markdown-features/markdown-features-admonitions.mdx
View file

@ -69,7 +69,7 @@ Danger danger, mayday!
::: :::
## Specifying title ## Specifying title {#specifying-title}
You may also specify an optional title You may also specify an optional title

8
website/versioned_docs/version-2.0.0-alpha.71/guides/markdown-features/markdown-features-assets.mdx
View file

@ -20,7 +20,7 @@ Let's imagine the following file structure:
/website/docs/assets/docusaurus-asset-example-pdf.pdf /website/docs/assets/docusaurus-asset-example-pdf.pdf
``` ```
## Images ## Images {#images}
You can use images in Markdown, or by requiring them and using a JSX image tag: You can use images in Markdown, or by requiring them and using a JSX image tag:
@ -57,7 +57,7 @@ If you are using [@docusaurus/plugin-ideal-image](../../using-plugins.md#docusau
::: :::
## Files ## 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.
@ -83,7 +83,7 @@ or
[Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf) [Download this PDF using Markdown](../../assets/docusaurus-asset-example-pdf.pdf)
## Inline SVGs ## Inline SVGs {#inline-svgs}
Docusaurus supports inlining SVGs out of the box. Docusaurus supports inlining SVGs out of the box.
@ -117,7 +117,7 @@ html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
<DocusaurusSvg className="themedDocusaurus" /> <DocusaurusSvg className="themedDocusaurus" />
## Themed Images ## Themed Images {#themed-images}
Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme. Docusaurus supports themed images: the `ThemedImage` component (included in the classic/bootstrap themes) allows you to switch the image source based on the current theme.

12
website/versioned_docs/version-2.0.0-alpha.71/guides/markdown-features/markdown-features-code-blocks.mdx
View file

@ -7,7 +7,7 @@ slug: /markdown-features/code-blocks
Code blocks within documentation are super-powered 💪. Code blocks within documentation are super-powered 💪.
## Code title ## 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 `title` key after the language (leave a space between them).
@ -23,7 +23,7 @@ function HelloCodeTitle(props) {
} }
``` ```
## Syntax highlighting ## 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 specifications of MDX.
@ -95,7 +95,7 @@ const prismIncludeLanguages = (Prism) => {
You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions. You can refer to [Prism's official language definitions](https://github.com/PrismJS/prism/tree/master/components) when you are writing your own language definitions.
## Line highlighting ## Line highlighting {#line-highlighting}
You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language). You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
@ -220,7 +220,7 @@ Supported commenting syntax:
If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome. If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
## Interactive code editor ## Interactive code editor {#interactive-code-editor}
(Powered by [React Live](https://github.com/FormidableLabs/react-live)) (Powered by [React Live](https://github.com/FormidableLabs/react-live))
@ -292,7 +292,7 @@ function Clock(props) {
} }
``` ```
### Imports ### Imports {#imports}
:::caution react-live and imports :::caution react-live and imports
@ -345,7 +345,7 @@ function MyPlayground(props) {
} }
``` ```
## Multi-language support code blocks ## 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 switching between them using a tabs component.

8
website/versioned_docs/version-2.0.0-alpha.71/guides/markdown-features/markdown-features-headings.mdx
View file

@ -5,7 +5,7 @@ description: Using Markdown headings
slug: /markdown-features/headings slug: /markdown-features/headings
--- ---
## Markdown headings ## Markdown headings {#markdown-headings}
You can use regular Markdown headings. You can use regular Markdown headings.
@ -19,7 +19,7 @@ You can use regular Markdown headings.
Markdown headings appear as a table-of-contents entry. Markdown headings appear as a table-of-contents entry.
## Heading ids ## 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.
@ -33,7 +33,7 @@ Heading ids allow you to link to a specific document heading in Markdown or JSX:
<Link to="#heading-id">link</Link> <Link to="#heading-id">link</Link>
``` ```
### Generated ids ### Generated ids {#generated-ids}
By default, Docusaurus will generate heading ids for you, based on the heading text. By default, Docusaurus will generate heading ids for you, based on the heading text.
@ -44,7 +44,7 @@ Generated ids have **some limits**:
- The id might not look good - The id might not look good
- You might want to **change or translate** the text without updating the existing id - You might want to **change or translate** the text without updating the existing id
### Explicit ids ### Explicit ids {#explicit-ids}
A special Markdown syntax lets you set an **explicit heading id**: A special Markdown syntax lets you set an **explicit heading id**:

28
website/versioned_docs/version-2.0.0-alpha.71/guides/markdown-features/markdown-features-inline-toc.mdx
View file

@ -11,7 +11,7 @@ Each markdown document displays a tab of content on the top-right corner.
But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX. But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
## Full table of contents ## Full table of contents {#full-table-of-contents}
The `toc` variable is available in any MDX document, and contain all the top level headings of a MDX document. The `toc` variable is available in any MDX document, and contain all the top level headings of a MDX document.
@ -31,7 +31,7 @@ import TOCInline from '@theme/TOCInline';
</BrowserWindow> </BrowserWindow>
``` ```
## Custom table of contents ## Custom table of contents {#custom-table-of-contents}
The `toc` props is just a list of table of contents items: The `toc` props is just a list of table of contents items:
@ -72,50 +72,50 @@ The underlying content is just an example to have more table-of-contents items a
::: :::
## Example Section 1 ## Example Section 1 {#example-section-1}
Lorem ipsum Lorem ipsum
### Example Subsection 1 a ### Example Subsection 1 a {#example-subsection-1-a}
Lorem ipsum Lorem ipsum
### Example Subsection 1 b ### Example Subsection 1 b {#example-subsection-1-b}
Lorem ipsum Lorem ipsum
### Example Subsection 1 c ### Example Subsection 1 c {#example-subsection-1-c}
Lorem ipsum Lorem ipsum
## Example Section 2 ## Example Section 2 {#example-section-2}
Lorem ipsum Lorem ipsum
### Example Subsection 2 a ### Example Subsection 2 a {#example-subsection-2-a}
Lorem ipsum Lorem ipsum
### Example Subsection 2 b ### Example Subsection 2 b {#example-subsection-2-b}
Lorem ipsum Lorem ipsum
### Example Subsection 2 c ### Example Subsection 2 c {#example-subsection-2-c}
Lorem ipsum Lorem ipsum
## Example Section 3 ## Example Section 3 {#example-section-3}
Lorem ipsum Lorem ipsum
### Example Subsection 3 a ### Example Subsection 3 a {#example-subsection-3-a}
Lorem ipsum Lorem ipsum
### Example Subsection 3 b ### Example Subsection 3 b {#example-subsection-3-b}
Lorem ipsum Lorem ipsum
### Example Subsection 3 c ### Example Subsection 3 c {#example-subsection-3-c}
Lorem ipsum Lorem ipsum

4
website/versioned_docs/version-2.0.0-alpha.71/guides/markdown-features/markdown-features-plugins.mdx
View file

@ -9,7 +9,7 @@ You can expand the MDX functionalities, using plugins.
Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX. Docusaurus content plugins support both [Remark](https://github.com/remarkjs/remark) and [Rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
## Configuring plugins ## Configuring plugins {#configuring-plugins}
An MDX plugin is usually a npm package, so you install them like other npm packages using npm. An MDX plugin is usually a npm package, so you install them like other npm packages using npm.
@ -50,7 +50,7 @@ module.exports = {
}; };
``` ```
## Configuring plugin options ## Configuring plugin options {#configuring-plugin-options}
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so: Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so:

4
website/versioned_docs/version-2.0.0-alpha.71/guides/markdown-features/markdown-features-tabs.mdx
View file

@ -50,7 +50,7 @@ By default, tabs are rendered eagerly, but it is possible to load them lazily by
::: :::
## Syncing tab choices ## 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 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.
@ -190,7 +190,7 @@ Tab choices with different `groupId`s will not interfere with each other:
</Tabs> </Tabs>
``` ```
## Customizing tabs ## 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 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:

46
website/versioned_docs/version-2.0.0-alpha.71/i18n/i18n-crowdin.mdx
View file

@ -25,7 +25,7 @@ Use this **[community-driven GitHub issue](https://github.com/facebook/docusauru
::: :::
## Crowdin overview ## Crowdin overview {#crowdin-overview}
Crowdin is a translation SaaS, offering a [free plan for open-source projects](https://crowdin.com/page/open-source-project-setup-request). Crowdin is a translation SaaS, offering a [free plan for open-source projects](https://crowdin.com/page/open-source-project-setup-request).
@ -41,13 +41,13 @@ The [`crowdin.yml` configuration file](https://support.crowdin.com/configuration
Read the **[official documentation](https://support.crowdin.com/)** to know more about advanced features and different translation workflows. Read the **[official documentation](https://support.crowdin.com/)** to know more about advanced features and different translation workflows.
## Crowdin tutorial ## Crowdin tutorial {#crowdin-tutorial}
This is a walk-through of using Crowdin to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md). This is a walk-through of using Crowdin to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
The end result can be seen at [docusaurus-crowdin-example.netlify.app](https://docusaurus-crowdin-example.netlify.app/) ([repository](https://github.com/slorber/docusaurus-crowdin-example)). The end result can be seen at [docusaurus-crowdin-example.netlify.app](https://docusaurus-crowdin-example.netlify.app/) ([repository](https://github.com/slorber/docusaurus-crowdin-example)).
### Prepare the Docusaurus site ### Prepare the Docusaurus site {#prepare-the-docusaurus-site}
Initialize a new Docusaurus site: Initialize a new Docusaurus site:
@ -99,7 +99,7 @@ export default function Home() {
} }
``` ```
### Create a Crowdin project ### Create a Crowdin project {#create-a-crowdin-project}
Sign up on [Crowdin](https://crowdin.com/), and create a project. Sign up on [Crowdin](https://crowdin.com/), and create a project.
@ -109,7 +109,7 @@ Use English as source language, and French as target language.
Your project is created, but it is empty for now. We will upload the files to translate in the next steps. Your project is created, but it is empty for now. We will upload the files to translate in the next steps.
### Create the Crowdin configuration ### Create the Crowdin configuration {#create-the-crowdin-configuration}
This configuration ([doc](https://support.crowdin.com/configuration-file/)) provides a mapping for the Crowdin CLI to understand: This configuration ([doc](https://support.crowdin.com/configuration-file/)) provides a mapping for the Crowdin CLI to understand:
@ -160,7 +160,7 @@ We advise to:
::: :::
#### Access token #### Access token {#access-token}
The `api_token_env` attribute defines the **env variable name** read by the Crowdin CLI. The `api_token_env` attribute defines the **env variable name** read by the Crowdin CLI.
@ -180,12 +180,12 @@ You should **not commit** it, and it may be a good idea to create a dedicated **
::: :::
#### Other configuration fields #### Other configuration fields {#other-configuration-fields}
- `project_id`: can be hardcoded, and is found on `https://crowdin.com/project/<MY_PROJECT_NAME>/settings#api` - `project_id`: can be hardcoded, and is found on `https://crowdin.com/project/<MY_PROJECT_NAME>/settings#api`
- `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything - `preserve_hierarchy`: preserve the folder's hierarchy of your docs on Crowdin UI instead of flattening everything
### Install the Crowdin CLI ### 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 use the CLI in version `3.5.2`, but we expect `3.x` releases to keep working.
@ -219,7 +219,7 @@ Temporarily, you can hardcode your personal token in `crowdin.yml` with `api_tok
::: :::
### Upload the sources ### Upload the sources {#upload-the-sources}
Generate the JSON translation files for the default language in `website/i18n/en`: Generate the JSON translation files for the default language in `website/i18n/en`:
@ -239,7 +239,7 @@ Your source files are now visible on the Crowdin interface: `https://crowdin.com
![Crowdin UI showing Docusaurus source files](/img/crowdin/crowdin-source-files.png) ![Crowdin UI showing Docusaurus source files](/img/crowdin/crowdin-source-files.png)
### Translate the sources ### Translate the sources {#translate-the-sources}
On `https://crowdin.com/project/<MY_PROJECT_NAME>`, click on the French target language. On `https://crowdin.com/project/<MY_PROJECT_NAME>`, click on the French target language.
@ -278,7 +278,7 @@ Use the `Hide String` feature first, as Crowdin is pre-translating things too op
::: :::
### Download the translations ### Download the translations {#download-the-translations}
Use the Crowdin CLI to download the translated JSON and Markdown files. Use the Crowdin CLI to download the translated JSON and Markdown files.
@ -296,7 +296,7 @@ npm run start -- --locale fr
Make sure that your website is now translated in French at `http://localhost:3000/fr/`. Make sure that your website is now translated in French at `http://localhost:3000/fr/`.
### Automate with CI ### 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.
@ -328,9 +328,9 @@ Crowdin does not support well multiple concurrent uploads/downloads: it is prefe
::: :::
## Advanced Crowdin topics ## Advanced Crowdin topics {#advanced-crowdin-topics}
### MDX ### MDX {#mdx}
:::caution :::caution
@ -340,7 +340,7 @@ Pay special attention to the JSX fragments in MDX documents!
Crowdin **does not support officially MDX**, but they added **support for the `.mdx` extension**, and interpret such files as Markdown (instead of plain text). Crowdin **does not support officially MDX**, but they added **support for the `.mdx` extension**, and interpret such files as Markdown (instead of plain text).
#### MDX problems #### 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 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.
@ -348,7 +348,7 @@ Simple JSX fragments using simple string props like `<Username name="Sebastien"/
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. 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 {#mdx-solutions}
We recommend moving the complex embedded JSX code as separate standalone components. We recommend moving the complex embedded JSX code as separate standalone components.
@ -394,7 +394,7 @@ This will:
- be interpreted by Docusaurus as regular JSX (as if it was not wrapped by any code block) - be interpreted by Docusaurus as regular JSX (as if it was not wrapped by any code block)
- unfortunately opt-out of MDX tooling (IDE syntax highlighting, Prettier...) - unfortunately opt-out of MDX tooling (IDE syntax highlighting, Prettier...)
### Docs versioning ### Docs versioning {#docs-versioning}
Configure translation files for the `website/versioned_docs` folder. Configure translation files for the `website/versioned_docs` folder.
@ -412,7 +412,7 @@ Not using `Hide` leads to a much larger amount of `source strings` in quotas, an
::: :::
### Multi-instance plugins ### Multi-instance plugins {#multi-instance-plugins}
You need to configure translation files for each plugin instance. You need to configure translation files for each plugin instance.
@ -421,7 +421,7 @@ If you have a docs plugin instance with `id=ios`, you will need to configure tho
- `website/ios` - `website/ios`
- `website/ios_versioned_docs` (if versioned) - `website/ios_versioned_docs` (if versioned)
### Maintaining your site ### Maintaining your site {#maintaining-your-site}
Sometimes, you will **remove or rename a source file** on Git, and Crowdin will display CLI warnings: Sometimes, you will **remove or rename a source file** on Git, and Crowdin will display CLI warnings:
@ -431,7 +431,7 @@ When your sources are refactored, you should use the Crowdin UI to **update your
![Crowdin UI: renaming a file](/img/crowdin/crowdin-files-rename.png) ![Crowdin UI: renaming a file](/img/crowdin/crowdin-files-rename.png)
### VCS (Git) integrations ### VCS (Git) integrations {#vcs-git-integrations}
Crowdin has multiple VCS integrations for [GitHub](https://support.crowdin.com/github-integration/), GitLab, Bitbucket. Crowdin has multiple VCS integrations for [GitHub](https://support.crowdin.com/github-integration/), GitLab, Bitbucket.
@ -451,7 +451,7 @@ In practice, **it didn't work very reliably** for a few reasons:
- 2 users concurrently editing on Git and Crowdin can lead to a translation loss - 2 users concurrently editing on Git and Crowdin can lead to a translation loss
- It requires the `crowdin.yml` file to be at the root of the repository - It requires the `crowdin.yml` file to be at the root of the repository
### In-Context localization ### In-Context localization {#in-context-localization}
Crowdin has an [In-Context localization](https://support.crowdin.com/in-context-localization/) feature. Crowdin has an [In-Context localization](https://support.crowdin.com/in-context-localization/) feature.
@ -463,7 +463,7 @@ Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`,
::: :::
### 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`. 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`.
@ -511,7 +511,7 @@ It is currently **not possible to link to a specific file** in Crowdin.
::: :::
### Example configuration ### Example configuration {#example-configuration}
The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance: The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance:

20
website/versioned_docs/version-2.0.0-alpha.71/i18n/i18n-git.md
View file

@ -7,7 +7,7 @@ slug: /i18n/git
A **possible translation strategy** is to **version control the translation files** to Git (or any other [VCS](https://en.wikipedia.org/wiki/Version_control)). A **possible translation strategy** is to **version control the translation files** to Git (or any other [VCS](https://en.wikipedia.org/wiki/Version_control)).
## Tradeoffs ## Tradeoffs {#tradeoffs}
This strategy has advantages: This strategy has advantages:
@ -31,11 +31,11 @@ Refer to the [Docusaurus i18n RFC](https://github.com/facebook/docusaurus/issues
::: :::
## Git tutorial ## Git tutorial {#git-tutorial}
This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md). This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
### Prepare the Docusaurus site ### Prepare the Docusaurus site {#prepare-the-docusaurus-site}
Initialize a new Docusaurus site: Initialize a new Docusaurus site:
@ -87,7 +87,7 @@ export default function Home() {
} }
``` ```
### Initialize the `i18n` folder ### Initialize the `i18n` folder {#initialize-the-i18n-folder}
Use the [write-translations](../cli.md#docusaurus-write-translations) CLI command to initialize the JSON translation files for the French locale: Use the [write-translations](../cli.md#docusaurus-write-translations) CLI command to initialize the JSON translation files for the French locale:
@ -124,7 +124,7 @@ cp -r pages/**.mdx i18n/fr/docusaurus-plugin-content-pages
Add all these files to Git. Add all these files to Git.
### Translate the files ### Translate the files {#translate-the-files}
Translate the Markdown and JSON files in `i18n/fr` and commit the translation. Translate the Markdown and JSON files in `i18n/fr` and commit the translation.
@ -142,21 +142,21 @@ npm run build
npm run build -- --locale fr npm run build -- --locale fr
``` ```
### Repeat ### Repeat {#repeat}
Follow the same process for each locale you need to support. Follow the same process for each locale you need to support.
## Maintain the translations ## Maintain the translations {#maintain-the-translations}
Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents. Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents.
### Markdown translations ### Markdown translations {#markdown-translations}
When an untranslated Markdown document is edited, it is **your responsibility to maintain the respective translated files**, and we unfortunately don't have a good way to help you do so. When an untranslated Markdown document is edited, it is **your responsibility to maintain the respective translated files**, and we unfortunately don't have a good way to help you do so.
To keep your translated sites consistent, when the `website/docs/doc1.md` doc is edited, you need **backport these edits** to `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`. To keep your translated sites consistent, when the `website/docs/doc1.md` doc is edited, you need **backport these edits** to `i18n/fr/docusaurus-plugin-content-docs/current/doc1.md`.
### JSON translations ### JSON translations {#json-translations}
To help you maintain the JSON translation files, it is possible to run again the [write-translations](../cli.md#docusaurus-write-translations) CLI command: To help you maintain the JSON translation files, it is possible to run again the [write-translations](../cli.md#docusaurus-write-translations) CLI command:
@ -172,7 +172,7 @@ Reset your translations with the `--override` option.
::: :::
### 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`. 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`.

18
website/versioned_docs/version-2.0.0-alpha.71/i18n/i18n-introduction.md
View file

@ -19,13 +19,13 @@ i18n requires Node 13+ to build or Node 12 with [full-icu](https://www.npmjs.com
::: :::
## Goals ## Goals {#goals}
It is important to understand the **design decisions** behind the Docusaurus i18n support. It is important to understand the **design decisions** behind the Docusaurus i18n support.
For more context, you can read the initial [RFC](https://github.com/facebook/docusaurus/issues/3317) and [PR](https://github.com/facebook/docusaurus/pull/3325). For more context, you can read the initial [RFC](https://github.com/facebook/docusaurus/issues/3317) and [PR](https://github.com/facebook/docusaurus/pull/3325).
### i18n goals ### i18n goals {#i18n-goals}
The goals of the Docusaurus i18n system are: The goals of the Docusaurus i18n system are:
@ -42,7 +42,7 @@ The goals of the Docusaurus i18n system are:
- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) should be easy to use - **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) should be easy to use
- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations). - **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations).
### i18n non-goals ### i18n non-goals {#i18n-non-goals}
We don't provide support for: We don't provide support for:
@ -50,9 +50,9 @@ We don't provide support for:
- **Translation SaaS software**: you are responsible to understand the external tools of your choice - **Translation SaaS software**: you are responsible to understand the external tools of your choice
- **Translation of slugs**: technically complicated, little SEO value - **Translation of slugs**: technically complicated, little SEO value
## Translation workflow ## Translation workflow {#translation-workflow}
### Overview ### Overview {#overview}
Overview of the workflow to create a translated Docusaurus website: Overview of the workflow to create a translated Docusaurus website:
@ -60,17 +60,17 @@ Overview of the workflow to create a translated Docusaurus website:
- **Translate**: put the translation files at the correct file-system location - **Translate**: put the translation files at the correct file-system location
- **Deploy**: build and deploy your site using a single or multi-domain strategy - **Deploy**: build and deploy your site using a single or multi-domain strategy
### Translation files ### Translation files {#translation-files}
You will have to work with 2 kind of translation files. You will have to work with 2 kind of translation files.
#### Markdown files #### Markdown files {#markdown-files}
This is the main content of your Docusaurus website. This is the main content of your Docusaurus website.
Markdown and MDX documents are translated as a whole, to fully preserve the translation context, instead of splitting each sentence as a separate string. Markdown and MDX documents are translated as a whole, to fully preserve the translation context, instead of splitting each sentence as a separate string.
#### JSON files #### JSON files {#json-files}
JSON is used to translate: JSON is used to translate:
@ -98,7 +98,7 @@ The choice was made for 2 reasons:
- **Description attribute**: to help translators with additional context - **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)
### Translation files location ### Translation files location {#translation-files-location}
The translation files should be created at the correct file-system location. The translation files should be created at the correct file-system location.

32
website/versioned_docs/version-2.0.0-alpha.71/i18n/i18n-tutorial.md
View file

@ -11,11 +11,11 @@ We will add **French** translations to a **newly initialized English Docusaurus
Initialize a new site with `npx @docusaurus/init@latest init website classic` (like [this one](https://github.com/facebook/docusaurus/tree/master/examples/classic)). Initialize a new site with `npx @docusaurus/init@latest init website classic` (like [this one](https://github.com/facebook/docusaurus/tree/master/examples/classic)).
## Configure your site ## Configure your site {#configure-your-site}
Modify `docusaurus.config.js` to add the i18n support for the French language. Modify `docusaurus.config.js` to add the i18n support for the French language.
### Site configuration ### Site configuration {#site-configuration}
Use the [site i18n configuration](./../api/docusaurus.config.js.md#i18n) to declare the i18n locales: Use the [site i18n configuration](./../api/docusaurus.config.js.md#i18n) to declare the i18n locales:
@ -36,7 +36,7 @@ module.exports = {
}; };
``` ```
### Theme configuration ### Theme configuration {#theme-configuration}
Add a **navbar item** of type `localeDropdown` so that users can select the locale they want: Add a **navbar item** of type `localeDropdown` so that users can select the locale they want:
@ -57,7 +57,7 @@ module.exports = {
}; };
``` ```
### Start your site ### Start your site {#start-your-site}
Start your localized site in dev mode, using the locale of your choice: Start your localized site in dev mode, using the locale of your choice:
@ -83,7 +83,7 @@ Each locale is a **distinct standalone single-page-application**: it is not poss
::: :::
## Translate your site ## Translate your site {#translate-your-site}
The French translations will be added in `website/i18n/fr`. The French translations will be added in `website/i18n/fr`.
@ -97,7 +97,7 @@ Hot-reload will work better when editing existing files.
::: :::
### Use the translation APIs ### Use the translation APIs {#use-the-translation-apis}
Open the homepage, and use the [translation APIs](../docusaurus-core.md#translate): Open the homepage, and use the [translation APIs](../docusaurus-core.md#translate):
@ -153,7 +153,7 @@ Most documentation websites are generally **static** and don't need advanced i18
::: :::
### Translate JSON files ### Translate JSON files {#translate-json-files}
JSON translation files are used for everything that is not contained in a Markdown document: JSON translation files are used for everything that is not contained in a Markdown document:
@ -210,11 +210,11 @@ Plugins and themes will also write their own **JSON translation files**, such as
Translate the `message` attribute in the JSON files of `i18n/fr`, and your site layout and homepage should now be translated. Translate the `message` attribute in the JSON files of `i18n/fr`, and your site layout and homepage should now be translated.
### Translate Markdown files ### Translate Markdown files {#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 {#translate-the-docs}
Copy your docs Markdown files to `i18n/fr/docusaurus-plugin-content-docs/current`, and translate them: Copy your docs Markdown files to `i18n/fr/docusaurus-plugin-content-docs/current`, and translate them:
@ -229,7 +229,7 @@ cp -r docs/** i18n/fr/docusaurus-plugin-content-docs/current
::: :::
#### Translate the blog #### Translate the blog {#translate-the-blog}
Copy your blog Markdown files to `i18n/fr/docusaurus-plugin-content-blog`, and translate them: Copy your blog Markdown files to `i18n/fr/docusaurus-plugin-content-blog`, and translate them:
@ -238,7 +238,7 @@ mkdir -p i18n/fr/docusaurus-plugin-content-blog
cp -r blog/** i18n/fr/docusaurus-plugin-content-blog cp -r blog/** i18n/fr/docusaurus-plugin-content-blog
``` ```
#### Translate the pages #### Translate the pages {#translate-the-pages}
Copy your pages Markdown files to `i18n/fr/docusaurus-plugin-content-pages`, and translate them: Copy your pages Markdown files to `i18n/fr/docusaurus-plugin-content-pages`, and translate them:
@ -254,7 +254,7 @@ We only copy `.md` and `.mdx` files, as pages React components are translated th
::: :::
### Use explicit heading ids ### Use explicit heading ids {#use-explicit-heading-ids}
By default, a Markdown heading `### Hello World` will have a generated id `hello-world`. By default, a Markdown heading `### Hello World` will have a generated id `hello-world`.
@ -275,11 +275,11 @@ For localized sites, it is recommended to use **[explicit heading ids](../guides
::: :::
## Deploy your site ## 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 {#single-domain-deployment}
Run the following command: Run the following command:
@ -313,7 +313,7 @@ This is not always possible, and depends on your host: GitHub Pages can't do thi
::: :::
### Multi-domain deployment ### Multi-domain deployment {#multi-domain-deployment}
You can also build your site for a single locale: You can also build your site for a single locale:
@ -335,7 +335,7 @@ This strategy is **not possible** with Github Pages, as it is only possible to *
::: :::
### Hybrid ### Hybrid {#hybrid}
It is possible to have some locales using sub-paths, and others using subdomains. It is possible to have some locales using sub-paths, and others using subdomains.

16
website/versioned_docs/version-2.0.0-alpha.71/installation.md
View file

@ -11,12 +11,12 @@ Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immedi
::: :::
## Requirements ## Requirements {#requirements}
- [Node.js](https://nodejs.org/en/download/) version >= 12.13.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed - [Node.js](https://nodejs.org/en/download/) version >= 12.13.0 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed
- [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged. - [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged.
## Scaffold project website ## Scaffold project website {#scaffold-project-website}
The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files. The easiest way to install Docusaurus is to use the command line tool that helps you scaffold a skeleton Docusaurus website. You can run this command anywhere in a new empty repository or within an existing repository, it will create a new directory containing the scaffolded files.
@ -50,7 +50,7 @@ If you want to skip installing dependencies, use the `--skip-install` option, li
npx @docusaurus/init@latest init my-website classic --skip-install npx @docusaurus/init@latest init my-website classic --skip-install
``` ```
## Project structure ## Project structure {#project-structure}
Assuming you chose the classic template and named your site `my-website`, you will see the following files generated under a new directory `my-website/`: 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/`:
@ -80,7 +80,7 @@ my-website
└── yarn.lock └── yarn.lock
``` ```
### Project structure rundown ### Project structure rundown {#project-structure-rundown}
- `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md) - `/blog/` - Contains the blog Markdown files. You can delete the directory if you do not want/need a blog. More details can be found in the [blog guide](blog.md)
- `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx) - `/docs/` - Contains the Markdown files for the docs. Customize the order of the docs sidebar in `sidebars.js`. More details can be found in the [docs guide](./guides/docs/docs-markdown-features.mdx)
@ -91,7 +91,7 @@ my-website
- `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them - `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them
- `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar - `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
## Running the development server ## Running the development server {#running-the-development-server}
To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest changes. To preview your changes as you edit the files, you can run a local development server that will serve your website and it will reflect the latest changes.
@ -104,7 +104,7 @@ By default, a browser window will open at http://localhost:3000.
Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available. Congratulations! You have just created your first Docusaurus site! Browse around the site to see what's available.
## Build ## Build {#build}
Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website: Docusaurus is a modern static website generator so we need to build the website into a directory of static contents and put it on a web server so that it can be viewed. To build the website:
@ -114,7 +114,7 @@ npm run build
and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.mdx) for more details. and contents will be generated within the `/build` directory, which can be copied to any static file hosting service like [GitHub pages](https://pages.github.com/), [Vercel](https://vercel.com/) or [Netlify](https://www.netlify.com/). Check out the docs on [deployment](deployment.mdx) for more details.
## Updating your Docusaurus version ## Updating your Docusaurus version {#updating-your-docusaurus-version}
There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version. There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version.
@ -152,6 +152,6 @@ Alternatively, if you are using Yarn, you can do:
yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49 yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49
``` ```
## Problems? ## Problems? {#problems}
Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/docusaurus), on our [GitHub repository](https://github.com/facebook/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) or [Twitter](https://twitter.com/docusaurus).

20
website/versioned_docs/version-2.0.0-alpha.71/introduction.md
View file

@ -5,7 +5,7 @@ description: Docusaurus was designed from the ground up to be easily installed a
slug: / slug: /
--- ---
## Disclaimer ## Disclaimer {#disclaimer}
Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable. Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable.
@ -32,7 +32,7 @@ Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immedi
- :x: You prefer stability over modernity - :x: You prefer stability over modernity
- :x: You need support for IE11 - :x: You need support for IE11
## A better Docusaurus is coming to town ## A better Docusaurus is coming to town {#a-better-docusaurus-is-coming-to-town}
![Docusaurus Slash Introduction](/img/slash-introducing.svg) ![Docusaurus Slash Introduction](/img/slash-introducing.svg)
@ -42,7 +42,7 @@ Beyond that, Docusaurus 2 is a **performant static site generator** and can be u
While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.** While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.**
## Features ## Features {#features}
Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors. Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors.
@ -76,13 +76,13 @@ Docusaurus 2 is born to be compassionately accessible to all your users, and lig
- ⚡️ **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 - ⚡️ **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 - 🦖 **Accessible** - Attention to accessibility, making your site equally accessible to all users
## Comparison with other tools ## Comparison with other tools {#comparison-with-other-tools}
Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need. Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.
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 to help you navigate through the prismatic choices out there.
### Gatsby ### Gatsby {#gatsby}
Gatsby 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 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.
@ -90,31 +90,31 @@ GraphQL is also pretty core to Gatsby, although you don't necessarily need Graph
Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative. Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
### GitBook ### GitBook {#gitbook}
GitBook 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 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).
Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone. Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
### Jekyll ### Jekyll {#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. 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 build pipeline and optimizations, and ease to setup.
### VuePress ### VuePress {#vuepress}
VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice. VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.
<!-- TODO: Add a Next.js comparison --> <!-- TODO: Add a Next.js comparison -->
## Staying informed ## Staying informed {#staying-informed}
- [GitHub](https://github.com/facebook/docusaurus) - [GitHub](https://github.com/facebook/docusaurus)
- [Twitter](https://twitter.com/docusaurus) - [Twitter](https://twitter.com/docusaurus)
- [Blog](/blog) - [Blog](/blog)
## Something missing? ## Something missing? {#something-missing}
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. 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.

50
website/versioned_docs/version-2.0.0-alpha.71/lifecycle-apis.md
View file

@ -11,15 +11,15 @@ This section is a work in progress.
Lifecycle APIs are shared by Themes and Plugins. Lifecycle APIs are shared by Themes and Plugins.
## `validateOptions({options, validate})` ## `validateOptions({options, validate})` {#validateoptionsoptions-validate}
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. 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.
### `options` ### `options` {#options}
`validateOptions` is called with `options` passed to plugin for validation and normalization. `validateOptions` is called with `options` passed to plugin for validation and normalization.
### `validate` ### `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 argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
@ -61,15 +61,15 @@ export function validateOptions({options, validate}) {
} }
``` ```
## `validateThemeConfig({themeConfig, validate})` ## `validateThemeConfig({themeConfig, validate})` {#validatethemeconfigthemeconfig-validate}
Return validated and normalized configuration for the theme. Return validated and normalized configuration for the theme.
### `themeConfig` ### `themeConfig` {#themeconfig}
`validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization. `validateThemeConfig` is called with `themeConfig` provided in `docusaurus.config.js` for validation and normalization.
### `validate` ### `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 argument, returns validated and normalized options. `validate` will automatically handle error and validation config.
@ -111,7 +111,7 @@ export function validateThemeConfig({themeConfig, validate}) {
} }
``` ```
## `getPathsToWatch()` ## `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. 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.
@ -130,7 +130,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `async loadContent()` ## `async loadContent()` {#async-loadcontent}
Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing. Plugins should use this lifecycle to fetch from data sources (filesystem, remote API, headless CMS, etc) or doing some server processing.
@ -148,15 +148,15 @@ module.exports = function (context, options) {
}; };
``` ```
## `async contentLoaded({content, actions})` ## `async contentLoaded({content, actions})` {#async-contentloadedcontent-actions}
Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data (optional). Plugins should use the data loaded in `loadContent` and construct the pages/routes that consume the loaded data (optional).
### `content` ### `content` {#content}
`contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`. `contentLoaded` will be called _after_ `loadContent` is done, the return value of `loadContent()` will be passed to `contentLoaded` as `content`.
### `actions` ### `actions` {#actions}
`actions` contain two functions: `actions` contain two functions:
@ -275,19 +275,19 @@ export default function friendsPlugin(context, options) {
} }
``` ```
## `configureWebpack(config, isServer, utils)` ## `configureWebpack(config, isServer, utils)` {#configurewebpackconfig-isserver-utils}
Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the argument argument. Modifies the internal webpack config. If the return value is a JavaScript object, it will be merged into the final config using [`webpack-merge`](https://github.com/survivejs/webpack-merge). If it is a function, it will be called and receive `config` as the first argument and an `isServer` flag as the argument argument.
### `config` ### `config` {#config}
`configureWebpack` is called with `config` generated according to client/server build. You may treat this as the base config to be merged with. `configureWebpack` is called with `config` generated according to client/server build. You may treat this as the base config to be merged with.
### `isServer` ### `isServer` {#isserver}
`configureWebpack` will be called both in server build and in client build. The server build receives `true` and the client build receives `false` as `isServer`. `configureWebpack` will be called both in server build and in client build. The server build receives `true` and the client build receives `false` as `isServer`.
### `utils` ### `utils` {#utils}
The initial call to `configureWebpack` also receives a util object consists of three functions: The initial call to `configureWebpack` also receives a util object consists of three functions:
@ -322,7 +322,7 @@ module.exports = function (context, options) {
}; };
``` ```
### Merge strategy ### Merge strategy {#merge-strategy}
We merge the Webpack configuration parts of plugins into the global Webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge). We merge the Webpack configuration parts of plugins into the global Webpack config using [webpack-merge](https://github.com/survivejs/webpack-merge).
@ -346,7 +346,7 @@ module.exports = function (context, options) {
Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details. Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details.
## `configurePostCss(options)` ## `configurePostCss(options)` {#configurepostcssoptions}
Modifies [`postcssOptions` of `postcss-loader`](https://webpack.js.org/loaders/postcss-loader/#postcssoptions) during the generation of the client bundle. Modifies [`postcssOptions` of `postcss-loader`](https://webpack.js.org/loaders/postcss-loader/#postcssoptions) during the generation of the client bundle.
@ -385,7 +385,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `postBuild(props)` ## `postBuild(props)` {#postbuildprops}
Called when a (production) build finishes. Called when a (production) build finishes.
@ -423,7 +423,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `extendCli(cli)` ## `extendCli(cli)` {#extendclicli}
Register an extra command to enhance the CLI of docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander) object. Register an extra command to enhance the CLI of docusaurus. `cli` is [commander](https://www.npmjs.com/package/commander) object.
@ -445,7 +445,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `injectHtmlTags()` ## `injectHtmlTags()` {#injecthtmltags}
Inject head and/or body HTML tags to Docusaurus generated HTML. Inject head and/or body HTML tags to Docusaurus generated HTML.
@ -512,7 +512,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `getThemePath()` ## `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 calls `swizzle`, `getThemePath` is called and its returned path is used to find your theme components.
@ -531,7 +531,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `getTypeScriptThemePath()` ## `getTypeScriptThemePath()` {#gettypescriptthemepath}
Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Instead, this path is purely for swizzling TypeScript theme components. Similar to `getThemePath()`, it should return the path to the directory where the source code of TypeScript theme components can be found. Theme components under this path will **not** be resolved by Webpack. Therefore, it is not a replacement of `getThemePath()`. Instead, this path is purely for swizzling TypeScript theme components.
@ -557,7 +557,7 @@ module.exports = function (context, options) {
}; };
``` ```
## `getSwizzleComponentList()` ## `getSwizzleComponentList()` {#getswizzlecomponentlist}
Return 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 then all components are considered unstable, if `undefined` is returned then all component are considered stable. Return 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 then all components are considered unstable, if `undefined` is returned then all component are considered stable.
@ -575,7 +575,7 @@ const swizzleAllowedComponents = [
module.exports.getSwizzleComponentList = () => swizzleAllowedComponents; module.exports.getSwizzleComponentList = () => swizzleAllowedComponents;
``` ```
## `getClientModules()` ## `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 in the client bundle. These modules are imported globally before React even renders the initial UI.
@ -602,7 +602,7 @@ For example, the in docusaurus-plugin-content-docs:
In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc. In contentLoaded, for each doc Markdown file, a route is created: /doc/installation, /doc/getting-started, etc.
--> -->
## Example ## Example {#example}
Here's a mind model for a presumptuous plugin implementation. Here's a mind model for a presumptuous plugin implementation.

2
website/versioned_docs/version-2.0.0-alpha.71/migration/migration-automated.md
View file

@ -50,7 +50,7 @@ The migration CLI updates existing files. Be sure to have commited them first!
::: :::
#### Options #### Options {#options}
You can add option flags to the migration CLI to automatically migrate Markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result. You can add option flags to the migration CLI to automatically migrate Markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.

66
website/versioned_docs/version-2.0.0-alpha.71/migration/migration-manual.md
View file

@ -6,11 +6,11 @@ slug: /migration/manual
This manual migration process should be run after the [automated migration process](./migration-automated.md), to complete the missing parts, or debug issues in the migration CLI output. This manual migration process should be run after the [automated migration process](./migration-automated.md), to complete the missing parts, or debug issues in the migration CLI output.
## Project setup ## Project setup {#project-setup}
### `package.json` ### `package.json` {#packagejson}
#### Scoped package names #### Scoped package names {#scoped-package-names}
In Docusaurus 2, we use scoped package names: In Docusaurus 2, we use scoped package names:
@ -36,7 +36,7 @@ Please use the most recent Docusaurus 2 alpha version, which you can check out [
::: :::
#### CLI commands #### CLI commands {#cli-commands}
Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`). Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`).
@ -85,7 +85,7 @@ A typical Docusaurus 2 `package.json` may look like this:
} }
``` ```
### Update references to the `build` directory ### Update references to the `build` directory {#update-references-to-the-build-directory}
In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`. In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`.
@ -93,7 +93,7 @@ In Docusaurus 2, it is now moved to just `website/build`. Make sure that you upd
If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of `yarn publish-gh-pages` script. If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of `yarn publish-gh-pages` script.
### `.gitignore` ### `.gitignore` {#gitignore}
The `.gitignore` in your `website` should contain: The `.gitignore` in your `website` should contain:
@ -120,13 +120,13 @@ yarn-debug.log*
yarn-error.log* yarn-error.log*
``` ```
### `README` ### `README` {#readme}
The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default [Docusaurus v2 README](https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-init/templates/classic/README.md). The D1 website may have an existing README file. You can modify it to reflect the D2 changes, or copy the default [Docusaurus v2 README](https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-init/templates/classic/README.md).
## Site configurations ## Site configurations {#site-configurations}
### `docusaurus.config.js` ### `docusaurus.config.js` {#docusaurusconfigjs}
Rename `siteConfig.js` to `docusaurus.config.js`. Rename `siteConfig.js` to `docusaurus.config.js`.
@ -160,13 +160,13 @@ If you are migrating your Docusaurus v1 website, and there are pending documenta
Refer to migration guide below for each field in `siteConfig.js`. Refer to migration guide below for each field in `siteConfig.js`.
### Updated fields ### Updated fields {#updated-fields}
#### `baseUrl`, `tagline`, `title`, `url`, `favicon`, `organizationName`, `projectName`, `githubHost`, `scripts`, `stylesheets` #### `baseUrl`, `tagline`, `title`, `url`, `favicon`, `organizationName`, `projectName`, `githubHost`, `scripts`, `stylesheets` {#baseurl-tagline-title-url-favicon-organizationname-projectname-githubhost-scripts-stylesheets}
No actions needed, these configuration fields were not modified. No actions needed, these configuration fields were not modified.
#### `colors` #### `colors` {#colors}
Deprecated. We wrote a custom CSS framework for Docusaurus 2 called [Infima](https://infima.dev/) which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`: Deprecated. We wrote a custom CSS framework for Docusaurus 2 called [Infima](https://infima.dev/) which uses CSS variables for theming. The docs are not quite ready yet and we will update here when it is. To overwrite Infima's CSS variables, create your own CSS file (e.g. `./src/css/custom.css`) and import it globally by passing it as an option to `@docusaurus/preset-classic`:
@ -212,7 +212,7 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
<ColorGenerator/> <ColorGenerator/>
#### `footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible` #### `footerIcon`, `copyright`, `ogImage`, `twitterImage`, `docsSideNavCollapsible` {#footericon-copyright-ogimage-twitterimage-docssidenavcollapsible}
Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the `themeConfig` field in your `docusaurus.config.js`: Site meta info such as assets, SEO, copyright info are now handled by themes. To customize them, use the `themeConfig` field in your `docusaurus.config.js`:
@ -236,7 +236,7 @@ module.exports = {
}; };
``` ```
#### `headerIcon`, `headerLinks` #### `headerIcon`, `headerLinks` {#headericon-headerlinks}
In Docusaurus 1, header icon and header links were root fields in `siteConfig`: In Docusaurus 1, header icon and header links were root fields in `siteConfig`:
@ -278,7 +278,7 @@ module.exports = {
}; };
``` ```
#### `algolia` #### `algolia` {#algolia}
```jsx {4-8} title="docusaurus.config.js" ```jsx {4-8} title="docusaurus.config.js"
module.exports = { module.exports = {
@ -294,7 +294,7 @@ module.exports = {
}; };
``` ```
#### `blogSidebarCount` #### `blogSidebarCount` {#blogsidebarcount}
Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead: Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead:
@ -315,11 +315,11 @@ module.exports = {
}; };
``` ```
#### `cname` #### `cname` {#cname}
Deprecated. Create a `CNAME` file in your `static` folder instead with your custom domain. Files in the `static` folder will be copied into the root of the `build` folder during execution of the build command. Deprecated. Create a `CNAME` file in your `static` folder instead with your custom domain. Files in the `static` folder will be copied into the root of the `build` folder during execution of the build command.
#### `customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime` #### `customDocsPath`, `docsUrl`, `editUrl`, `enableUpdateBy`, `enableUpdateTime` {#customdocspath-docsurl-editurl-enableupdateby-enableupdatetime}
**BREAKING**: `editUrl` should point to (website) Docusaurus project instead of `docs` directory. **BREAKING**: `editUrl` should point to (website) Docusaurus project instead of `docs` directory.
@ -354,7 +354,7 @@ module.exports = {
}; };
``` ```
#### `gaTrackingId` #### `gaTrackingId` {#gatrackingid}
```jsx {5} title="docusaurus.config.js" ```jsx {5} title="docusaurus.config.js"
module.exports = { module.exports = {
@ -368,7 +368,7 @@ module.exports = {
}; };
``` ```
#### `gaGtag` #### `gaGtag` {#gagtag}
```jsx {5} title="docusaurus.config.js" ```jsx {5} title="docusaurus.config.js"
module.exports = { module.exports = {
@ -382,7 +382,7 @@ module.exports = {
}; };
``` ```
### Removed fields ### Removed fields {#removed-fields}
The following fields are all deprecated, you may remove from your configuration file. The following fields are all deprecated, you may remove from your configuration file.
@ -414,7 +414,7 @@ The following fields are all deprecated, you may remove from your configuration
We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated! We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
## Urls ## Urls {#urls}
In v1, all pages were available with or without the `.html` extension. In v1, all pages were available with or without the `.html` extension.
@ -451,9 +451,9 @@ 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` frontmatter.
## Components ## Components {#components}
### Sidebar ### Sidebar {#sidebar}
In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](../guides/docs/sidebar.md#understanding-sidebar-items) other than document. In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](../guides/docs/sidebar.md#understanding-sidebar-items) other than document.
@ -469,7 +469,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
}, },
``` ```
### Footer ### Footer {#footer}
`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it: `website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
@ -495,7 +495,7 @@ module.exports = {
}; };
``` ```
### Pages ### Pages {#pages}
Please refer to [creating pages](guides/creating-pages.md) to learn how Docusaurus 2 pages work. After reading that, notice that you have to move `pages/en` files in v1 to `src/pages` instead. Please refer to [creating pages](guides/creating-pages.md) to learn how Docusaurus 2 pages work. After reading that, notice that you have to move `pages/en` files in v1 to `src/pages` instead.
@ -548,13 +548,13 @@ The following code could be helpful for migration of various pages:
- Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/) - Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js/) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js/), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js/)
- Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support) - Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js/), [Flux](http://facebook.github.io/flux/support)
## Content ## Content {#content}
### Replace AUTOGENERATED_TABLE_OF_CONTENTS ### Replace AUTOGENERATED_TABLE_OF_CONTENTS {#replace-autogenerated_table_of_contents}
This feature is replaced by [inline table of content](../guides/markdown-features/markdown-features-inline-toc.mdx) This feature is replaced by [inline table of content](../guides/markdown-features/markdown-features-inline-toc.mdx)
### Update Markdown syntax to be MDX-compatible ### Update Markdown syntax to be MDX-compatible {#update-markdown-syntax-to-be-mdx-compatible}
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. 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.
@ -562,23 +562,23 @@ Frontmatter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-mat
**Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier. **Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier.
### Language-specific code tabs ### Language-specific code tabs {#language-specific-code-tabs}
Refer to the [multi-language support code blocks](../guides/markdown-features/markdown-features-code-blocks.mdx#multi-language-support-code-blocks) section. Refer to the [multi-language support code blocks](../guides/markdown-features/markdown-features-code-blocks.mdx#multi-language-support-code-blocks) section.
### Front matter ### Front matter {#front-matter}
The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs. The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field. The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field.
## Deployment ## Deployment {#deployment}
The `CNAME` file used by GitHub Pages is not generated anymore, so be sure you have created it in `/static/CNAME` if you use a custom domain. The `CNAME` file used by GitHub Pages is not generated anymore, so be sure you have created it in `/static/CNAME` if you use a custom domain.
The blog RSS feed is now hosted at `/blog/rss.xml` instead of `/blog/feed.xml`. You may want to configure server-side redirects so that users' subscriptions keep working. The blog RSS feed is now hosted at `/blog/rss.xml` instead of `/blog/feed.xml`. You may want to configure server-side redirects so that users' subscriptions keep working.
## Test your site ## Test your site {#test-your-site}
After migration, your folder structure should look like this: After migration, your folder structure should look like this:

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