mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-06 10:20:09 +02:00
docs(v2): use codeblock title syntax instead of comments (#2473)
This commit is contained in:
Yangshun Tay
GitHub
parent
b8c888b1b1
commit
36ea74504e
19 changed files with 114 additions and 211 deletions
|
|
@ -91,8 +91,7 @@ feedOptions?: {
|
|||
|
||||
Example usage:
|
||||
|
||||
```js {9-12}
|
||||
// docusaurus.config.js
|
||||
```js {8-11} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -133,8 +132,7 @@ You can run your Docusaurus 2 site without a landing page and instead have your
|
|||
|
||||
**Note:** Make sure there's no `index.js` page in `src/pages` or else there will be two files mapping to the same route!
|
||||
|
||||
```js {10}
|
||||
// docusaurus.config.js
|
||||
```js {9} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
|
|||
|
|
@ -7,8 +7,7 @@ Docusaurus provides a set of scripts to help you generate, serve, and deploy you
|
|||
|
||||
Once your website is generated, your website package will contain the Docusaurus scripts that you may invoke with your package manager:
|
||||
|
||||
```json
|
||||
// package.json
|
||||
```json title="package.json"
|
||||
{
|
||||
// ...
|
||||
"scripts": {
|
||||
|
|
|
|||
|
|
@ -38,8 +38,7 @@ It is recommended to check the [deployment docs](deployment.md) for more informa
|
|||
|
||||
List the installed [themes](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:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
|
|
@ -52,8 +51,7 @@ module.exports = {
|
|||
|
||||
They can also be loaded from local directories:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
|
|
@ -64,8 +62,7 @@ module.exports = {
|
|||
|
||||
To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
|
|
@ -85,8 +82,7 @@ module.exports = {
|
|||
|
||||
To specify options for a plugin or theme that is bundled in a preset, pass the options through the `presets` field. In this example, `docs` refers to `@docusaurus/plugin-content-docs` and `theme` refers to `@docusaurus/theme-classic`.
|
||||
|
||||
```js
|
||||
//docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -113,13 +109,14 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi
|
|||
|
||||
Example:
|
||||
|
||||
```js {3-6}
|
||||
// docusaurus.config.js
|
||||
```js {3-6} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
customFields: {
|
||||
image: '',
|
||||
keywords: [],
|
||||
},
|
||||
...
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -156,8 +153,7 @@ Here are some steps you need to follow for a "docs-only mode":
|
|||
|
||||
1. Set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site:
|
||||
|
||||
```js {9}
|
||||
// docusaurus.config.js
|
||||
```js {8} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
|
|||
|
|
@ -56,7 +56,7 @@ You may refer to GitHub Pages' documentation [User, Organization, and Project Pa
|
|||
|
||||
Example:
|
||||
|
||||
```jsx {3-6}
|
||||
```jsx {3-6} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
url: 'https://endiliey.github.io', // Your website URL
|
||||
|
|
@ -117,11 +117,11 @@ References:
|
|||
|
||||
To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
|
||||
|
||||
```js {3-4}
|
||||
// docusaurus.config.js
|
||||
```js {2-3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
url: 'https://docusaurus-2.netlify.com', // url to your site with no trailing slash
|
||||
baseUrl: '/', // base directory of your site relative to your repo
|
||||
...
|
||||
};
|
||||
```
|
||||
|
||||
|
|
@ -160,7 +160,7 @@ Render offers [free static site hosting](https://render.com/docs/static-sites) w
|
|||
|
||||
That's it! Your app will be live on your Render URL as soon as the build finishes.
|
||||
|
||||
### Deplying to Travis CI
|
||||
### Deploying to 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 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.
|
||||
|
||||
|
|
@ -170,8 +170,7 @@ Continuous integration (CI) services are typically used to perform routine tasks
|
|||
1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
|
||||
1. Create a `.travis.yml` on the root of your repository with the following:
|
||||
|
||||
```yaml
|
||||
# .travis.yml
|
||||
```yaml title=".travis.yml"
|
||||
language: node_js
|
||||
node_js:
|
||||
- '10'
|
||||
|
|
|
|||
|
|
@ -16,8 +16,7 @@ description: API reference for Docusaurus configuration file.
|
|||
|
||||
Title for your website.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
title: 'Docusaurus',
|
||||
};
|
||||
|
|
@ -29,8 +28,7 @@ module.exports = {
|
|||
|
||||
URL for site favicon. Example:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
favicon: 'https://v2.docusaurus.io/favicon.ico',
|
||||
};
|
||||
|
|
@ -49,8 +47,7 @@ You can also use the favicon URL relative to the `static` directory of your site
|
|||
|
||||
So you can refer it like below:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
favicon: 'img/favicon.ico',
|
||||
};
|
||||
|
|
@ -62,8 +59,7 @@ module.exports = {
|
|||
|
||||
URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the URL of https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL for https://docusaurus.io. This field is related to the [baseUrl](#baseurl) field.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
url: 'https://docusaurus.io',
|
||||
};
|
||||
|
|
@ -75,8 +71,7 @@ module.exports = {
|
|||
|
||||
Base URL for your site. This can also be considered the path after the host. For example, `/metro/` is the baseUrl of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [url](#url) field.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
baseUrl: '/',
|
||||
};
|
||||
|
|
@ -90,8 +85,7 @@ module.exports = {
|
|||
|
||||
The tagline for your website.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
tagline:
|
||||
'Docusaurus makes it easy to maintain Open Source documentation websites.',
|
||||
|
|
@ -104,10 +98,9 @@ module.exports = {
|
|||
|
||||
The GitHub user or organization that owns the repository. Used by the deployment command.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// Docusaurus's organization is facebook
|
||||
// Docusaurus' organization is facebook
|
||||
organizationName: 'facebook',
|
||||
};
|
||||
```
|
||||
|
|
@ -118,8 +111,7 @@ module.exports = {
|
|||
|
||||
The name of the GitHub repository. Used by the deployment command.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
projectName: 'docusaurus',
|
||||
};
|
||||
|
|
@ -131,8 +123,7 @@ module.exports = {
|
|||
|
||||
The hostname of your server. Useful if you are using GitHub Enterprise.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
githubHost: 'github.com',
|
||||
};
|
||||
|
|
@ -150,8 +141,7 @@ For Docusaurus' default theme _classic_, we use `themeConfig` to customize your
|
|||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
|
|
@ -200,8 +190,7 @@ module.exports = {
|
|||
|
||||
- Type: `any[]`
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [],
|
||||
};
|
||||
|
|
@ -213,8 +202,7 @@ module.exports = {
|
|||
|
||||
- Type: `any[]`
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themes: [],
|
||||
};
|
||||
|
|
@ -226,8 +214,7 @@ module.exports = {
|
|||
|
||||
- Type: `any[]`
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [],
|
||||
};
|
||||
|
|
@ -239,8 +226,7 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi
|
|||
|
||||
- Type: `Object`
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
customFields: {
|
||||
admin: 'endi',
|
||||
|
|
@ -265,8 +251,7 @@ Note that `<script>` added here are render-blocking so you might want to add `as
|
|||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
scripts: [
|
||||
// String format.
|
||||
|
|
@ -289,8 +274,7 @@ An array of CSS sources to load. The values can be either strings or plain objec
|
|||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
stylesheets: [
|
||||
// String format.
|
||||
|
|
|
|||
|
|
@ -17,8 +17,7 @@ Specifies the paths to watch for plugins and themes. The paths are watched by th
|
|||
|
||||
Example:
|
||||
|
||||
```js {6-8}
|
||||
// docusaurus-plugin/src/index.js
|
||||
```js {5-7} title="docusaurus-plugin/src/index.js"
|
||||
const path = require('path');
|
||||
module.exports = function(context, options) {
|
||||
return {
|
||||
|
|
@ -37,8 +36,7 @@ Plugins should use this lifecycle to fetch from data sources (filesystem, remote
|
|||
|
||||
For example, this plugin below return a random integer between 1 to 10 as content;
|
||||
|
||||
```js {6-7}
|
||||
// docusaurus-plugin/src/index.js
|
||||
```js {5-6} title="docusaurus-plugin/src/index.js"
|
||||
const path = require('path');
|
||||
module.exports = function(context, options) {
|
||||
return {
|
||||
|
|
@ -93,8 +91,7 @@ A helper function to help you write some data (usually a string or JSON) to disk
|
|||
|
||||
For example, this plugin below create a `/roll` page which display "You won xxxx" to user.
|
||||
|
||||
```jsx
|
||||
// website/src/components/roll.js
|
||||
```jsx title="website/src/components/roll.js"
|
||||
import React from 'react';
|
||||
|
||||
export default function(props) {
|
||||
|
|
@ -104,8 +101,7 @@ export default function(props) {
|
|||
}
|
||||
```
|
||||
|
||||
```javascript {5-20}
|
||||
// docusaurus-plugin/src/index.js
|
||||
```javascript {4-19} title="docusaurus-plugin/src/index.js"
|
||||
module.exports = function(context, options) {
|
||||
return {
|
||||
name: 'docusaurus-plugin',
|
||||
|
|
@ -154,8 +150,7 @@ You may use them to return your webpack configures conditionally.
|
|||
|
||||
For example, this plugin below modify the webpack config to transpile `.foo` file.
|
||||
|
||||
```js {5-12}
|
||||
// docusaurus-plugin/src/index.js
|
||||
```js {4-11} title="docusaurus-plugin/src/index.js"
|
||||
module.exports = function(context, options) {
|
||||
return {
|
||||
name: 'custom-docusaurus-plugin',
|
||||
|
|
@ -176,7 +171,7 @@ module.exports = function(context, options) {
|
|||
};
|
||||
```
|
||||
|
||||
## postBuild(props)
|
||||
## `postBuild(props)`
|
||||
|
||||
Called when a (production) build finishes.
|
||||
|
||||
|
|
@ -197,8 +192,7 @@ type Props = {
|
|||
|
||||
Example:
|
||||
|
||||
```js {5-10}
|
||||
// docusaurus-plugin/src/index.js
|
||||
```js {4-9} title="docusaurus-plugin/src/index.js"
|
||||
module.exports = function(context, options) {
|
||||
return {
|
||||
name: 'docusaurus-plugin',
|
||||
|
|
@ -218,8 +212,7 @@ Register an extra command to enhance the CLI of docusaurus. `cli` is [commander]
|
|||
|
||||
Example:
|
||||
|
||||
```js {5-12}
|
||||
// docusaurus-plugin/src/index.js
|
||||
```js {4-11} title="docusaurus-plugin/src/index.js"
|
||||
module.exports = function(context, options) {
|
||||
return {
|
||||
name: 'docusaurus-plugin',
|
||||
|
|
@ -269,8 +262,7 @@ interface HtmlTagObject {
|
|||
|
||||
Example:
|
||||
|
||||
```js {5-29}
|
||||
// docusaurus-plugin/src/index.js
|
||||
```js {4-28} title="docusaurus-plugin/src/index.js"
|
||||
module.exports = function(context, options) {
|
||||
return {
|
||||
name: 'docusaurus-plugin',
|
||||
|
|
@ -307,8 +299,7 @@ Returns the path to the directory where the theme components can be found. When
|
|||
|
||||
If you use the folder directory above, your `getThemePath` can be:
|
||||
|
||||
```js {7-9}
|
||||
// my-theme/src/index.js
|
||||
```js {6-8} title="my-theme/src/index.js"
|
||||
const path = require('path');
|
||||
|
||||
module.exports = function(context, options) {
|
||||
|
|
@ -327,8 +318,7 @@ Returns an array of paths to the modules that are to be imported in the client b
|
|||
|
||||
As an example, to make your theme load a `customCss` object from `options` passed in by the user:
|
||||
|
||||
```js {8-10}
|
||||
// my-theme/src/index.js
|
||||
```js {7-9} title="my-theme/src/index.js"
|
||||
const path = require('path');
|
||||
|
||||
module.exports = function(context, options) {
|
||||
|
|
|
|||
|
|
@ -212,8 +212,7 @@ By default, the Prism [syntax highlighting theme](https://github.com/FormidableL
|
|||
|
||||
For example, if you prefer to use the `dracula` highlighting theme:
|
||||
|
||||
```js {4}
|
||||
// docusaurus.config.js
|
||||
```js {3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
prism: {
|
||||
|
|
@ -230,8 +229,7 @@ define it in an array of additional languages.
|
|||
|
||||
For example, if you want to add highlighting for the `powershell` language:
|
||||
|
||||
```js
|
||||
// docusaurus/config.js
|
||||
```js {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
@ -269,8 +267,7 @@ function HighlightSomeText(highlight) {
|
|||
|
||||
To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
|
||||
|
||||
```css
|
||||
/* /src/css/custom.css */
|
||||
```css title="/src/css/custom.css"
|
||||
.docusaurus-highlight-code-line {
|
||||
background-color: rgb(72, 77, 91);
|
||||
display: block;
|
||||
|
|
@ -352,8 +349,7 @@ const rehypeTruncate = require('rehype-truncate');
|
|||
|
||||
Finally, add them to the `@docusaurus/preset-classic` options in `docusaurus.config.js`:
|
||||
|
||||
```js {11,12}
|
||||
// docusaurus.config.js
|
||||
```js {10,11} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -376,8 +372,7 @@ module.exports = {
|
|||
|
||||
Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like so:
|
||||
|
||||
```jsx {11-14}
|
||||
// docusaurus.config.js
|
||||
```jsx {10-13} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
|
|||
|
|
@ -139,8 +139,7 @@ Rename `siteConfig.js` to `docusaurus.config.js`. In Docusaurus 2, we split each
|
|||
|
||||
Add the following preset configuration to your `docusaurus.config.js`.
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
```jsx title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -174,8 +173,7 @@ No actions needed.
|
|||
|
||||
Deprecated. We wrote a custom CSS framework for Docusaurus 2 called Infima 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`:
|
||||
|
||||
```js {8-10}
|
||||
// docusaurus.config.js
|
||||
```js {7-9} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -193,9 +191,8 @@ module.exports = {
|
|||
|
||||
Infima uses 7 shades of each color.
|
||||
|
||||
```css
|
||||
```css title="/src/css/custom.css"
|
||||
/**
|
||||
* /src/css/custom.css
|
||||
* You can override the default Infima variables here.
|
||||
* Note: this is not a complete list of --ifm- variables.
|
||||
*/
|
||||
|
|
@ -220,8 +217,7 @@ Alteratively, use the following tool to generate the different shades for your w
|
|||
|
||||
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`:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
```jsx title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
|
|
@ -257,8 +253,7 @@ headerLinks: [
|
|||
|
||||
Now, these two fields are both handled by the theme:
|
||||
|
||||
```jsx {7-20}
|
||||
// docusaurus.config.js
|
||||
```jsx {6-19} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
|
|
@ -286,8 +281,7 @@ module.exports = {
|
|||
|
||||
#### `algolia`
|
||||
|
||||
```jsx {5-9}
|
||||
// docusaurus.config.js
|
||||
```jsx {4-8} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
|
|
@ -305,8 +299,7 @@ module.exports = {
|
|||
|
||||
Deprecated. Pass it as a blog option to `@docusaurus/preset-classic` instead:
|
||||
|
||||
```jsx {9}
|
||||
// docusaurus.config.js
|
||||
```jsx {8} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -333,8 +326,7 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust
|
|||
|
||||
Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
|
||||
|
||||
```jsx {9-22}
|
||||
// docusaurus.config.js
|
||||
```jsx {8-21} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -365,8 +357,7 @@ module.exports = {
|
|||
|
||||
#### `gaTrackingId`
|
||||
|
||||
```jsx {6}
|
||||
// docusaurus.config.js
|
||||
```jsx {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
|
|
@ -380,8 +371,7 @@ module.exports = {
|
|||
|
||||
#### `gaGtag`
|
||||
|
||||
```jsx {6}
|
||||
// docusaurus.config.js
|
||||
```jsx {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themeConfig: {
|
||||
|
|
@ -643,8 +633,7 @@ In v2, we use snapshot approach on documentation versioning. **Every versioned d
|
|||
|
||||
For example, if your `versions.json` looks like this in v1
|
||||
|
||||
```json
|
||||
// versions.json
|
||||
```json title="versions.json"
|
||||
["1.1.0", "1.0.0"]
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -15,8 +15,7 @@ npm install --save docusaurus-preset-name
|
|||
|
||||
Then, add it in your site's `docusaurus.config.js`'s `presets` option:
|
||||
|
||||
```jsx {4}
|
||||
// docusaurus.config.js
|
||||
```jsx {3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: ['@docusaurus/preset-xxxx'],
|
||||
|
|
@ -25,8 +24,7 @@ module.exports = {
|
|||
|
||||
To load presets from your local directory, specify how to resolve them:
|
||||
|
||||
```jsx {6}
|
||||
// docusaurus.config.js
|
||||
```jsx {5} title="docusaurus.config.js"
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
|
|
@ -50,18 +48,16 @@ module.exports = function preset(context, opts = {}) {
|
|||
|
||||
then in your Docusaurus config, you may configure the preset instead:
|
||||
|
||||
```jsx {4}
|
||||
// docusaurus.config.js
|
||||
```jsx {3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: ['@docusaurus/preset-a'],
|
||||
presets: ['@docusaurus/preset-my-own'],
|
||||
};
|
||||
```
|
||||
|
||||
This is equivalent of doing:
|
||||
|
||||
```jsx
|
||||
// docusaurus.config.js
|
||||
```jsx title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themes: ['@docusaurus/themes-cool', '@docusaurus/themes-bootstrap'],
|
||||
plugins: ['@docusaurus/plugin-blog'],
|
||||
|
|
@ -87,8 +83,7 @@ The classic preset that is usually shipped by default to new docusaurus website.
|
|||
|
||||
To specify plugin options individually, you can provide the necessary fields to certain plugins, i.e. `customCss` for `@docusaurus/theme-classic`, pass them in the preset field, like this:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
|
|
@ -116,8 +111,7 @@ In addition to these plugins and themes, `@docusaurus/theme-classic` adds [`rema
|
|||
|
||||
The `admonitions` key will be passed as the [options](https://github.com/elviswolcott/remark-admonitions#options) to `remark-admonitions`. Passing `false` will prevent the plugin from being added to MDX.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
|
|
|
|||
|
|
@ -18,10 +18,9 @@ Algolia DocSearch works by crawling the content of your website every 24 hours a
|
|||
|
||||
To connect your docs with Algolia, add an `algolia` field in your `themeConfig`. Note that you will need algolia API key and algolia index. You can [apply for DocSearch here](https://community.algolia.com/docsearch/).
|
||||
|
||||
```jsx {4-9}
|
||||
// docusaurus.config.js
|
||||
```jsx {3-8} title="docusaurus.config.js"
|
||||
themeConfig: {
|
||||
// ....
|
||||
// ...
|
||||
algolia: {
|
||||
appId: 'app-id',
|
||||
apiKey: 'api-key',
|
||||
|
|
|
|||
|
|
@ -5,8 +5,7 @@ title: Sidebar
|
|||
|
||||
To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
|
||||
|
||||
```js {9-10}
|
||||
// docusaurus.config.js
|
||||
```js {8-9} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -40,8 +39,7 @@ type Sidebar = {
|
|||
|
||||
Below is an example of a sidebar object. The key `docs` is the id of the sidebar (can be renamed to something else) and `Getting Started` is a category within the sidebar. `greeting` and `doc1` are both [sidebar item](#sidebar-item).
|
||||
|
||||
```js
|
||||
// sidebars.js
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
docs: {
|
||||
'Getting started': ['greeting'],
|
||||
|
|
@ -52,8 +50,7 @@ module.exports = {
|
|||
|
||||
Keep in mind that EcmaScript does not guarantee `Object.keys({a,b}) === ['a','b']` (yet, this is generally true). If you don't want to rely on iteration order of JavaScript object keys for the category name, the following sidebar object is also equivalent of the above shorthand syntax.
|
||||
|
||||
```js
|
||||
// sidebars.js
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
docs: [
|
||||
{
|
||||
|
|
@ -74,8 +71,7 @@ You can also have multiple sidebars for different Markdown files by adding more
|
|||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// sidebars.js
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
firstSidebar: {
|
||||
'Category A': ['doc1'],
|
||||
|
|
@ -147,8 +143,7 @@ Using just the [Document ID](#document-id) is perfectly valid as well, the follo
|
|||
|
||||
Note that using this type will bind the linked doc to current sidebar, this means that if you access `doc1` page, the sidebar displayed will be the sidebar this item is on. For below case, `doc1` is bounded to `firstSidebar`.
|
||||
|
||||
```js
|
||||
// sidebars.js
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
firstSidebar: {
|
||||
'Category A': ['doc1'],
|
||||
|
|
@ -212,8 +207,7 @@ type SidebarItemCategory = {
|
|||
|
||||
As an example, here's how we created the subcategory for "Docs" under "Guides" in this site:
|
||||
|
||||
```js
|
||||
// sidebars.js
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
docs: {
|
||||
Guides: [
|
||||
|
|
@ -230,8 +224,7 @@ module.exports = {
|
|||
|
||||
**Note**: it's possible to use the shorthand syntax to create nested categories:
|
||||
|
||||
```js
|
||||
// sidebars.js
|
||||
```js title="sidebars.js"
|
||||
module.exports = {
|
||||
docs: {
|
||||
Guides: [
|
||||
|
|
@ -248,8 +241,7 @@ module.exports = {
|
|||
|
||||
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`:
|
||||
|
||||
```js {5}
|
||||
// docusaurus.config.js
|
||||
```js {4} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
|
|||
|
|
@ -15,8 +15,7 @@ A better way would be to use the `useBaseUrl` utility function which appends the
|
|||
|
||||
### JSX example
|
||||
|
||||
```jsx
|
||||
// MyComponent.js
|
||||
```jsx title="MyComponent.js"
|
||||
import useBaseUrl from '@docusaurus/useBaseUrl';
|
||||
|
||||
<img
|
||||
|
|
@ -29,8 +28,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
|
|||
|
||||
Thanks to MDX, you can also use `useBaseUrl` utility function in Markdown files! You'd have to use `<img>` tags instead of the Markdown image syntax though. The syntax is exactly the same as in JSX.
|
||||
|
||||
```txt
|
||||
// my-doc.mdx
|
||||
```txt title="my-doc.mdx"
|
||||
---
|
||||
id: my-doc
|
||||
title: My Doc
|
||||
|
|
@ -45,9 +43,7 @@ import useBaseUrl from '@docusaurus/useBaseUrl'; // Add to the top of the file b
|
|||
|
||||
You could also just use Markdown image syntax, but you would have to manually maintain the image paths yourself and isn't recommended.
|
||||
|
||||
```md
|
||||
// my-doc.md
|
||||
|
||||
```md title="my-doc.md"
|
||||
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -10,8 +10,7 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
|
|||
|
||||
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.
|
||||
|
||||
```js {8-10}
|
||||
// docusaurus.config.js
|
||||
```js {7-9} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
presets: [
|
||||
|
|
@ -35,9 +34,8 @@ Any CSS you write within that file will be available globally and can be referen
|
|||
|
||||
When you `init` your Docusaurus 2 project, the website will be generated with basic Infima stylesheets and default styling. You may customize the styling by editing the `src/css/custom.css` file.
|
||||
|
||||
```css
|
||||
```css title="/src/css/custom.css"
|
||||
/**
|
||||
* /src/css/custom.css
|
||||
* You can override the default Infima variables here.
|
||||
* Note: this is not a complete list of --ifm- variables.
|
||||
*/
|
||||
|
|
@ -73,8 +71,7 @@ This is the most traditional way of styling that most developers (including non-
|
|||
|
||||
Assuming you are using `@docusaurus/preset-classic` and `/src/css/custom.css` was passed in to the preset config, styles inside that file would be available globally.
|
||||
|
||||
```css
|
||||
/* /src/css/custom.css */
|
||||
```css title="/src/css/custom.css"
|
||||
.purple-text {
|
||||
color: rebeccapurple;
|
||||
}
|
||||
|
|
@ -94,8 +91,7 @@ function MyComponent() {
|
|||
|
||||
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).
|
||||
|
||||
```css
|
||||
/* styles.module.css */
|
||||
```css title="styles.module.css"
|
||||
.main {
|
||||
padding: 12px;
|
||||
}
|
||||
|
|
@ -144,8 +140,7 @@ npm install --save docusaurus-plugin-sass
|
|||
|
||||
2. Include the plugin in your `docusaurus.config.js` file:
|
||||
|
||||
```jsx {4}
|
||||
// docusaurus.config.js
|
||||
```jsx {3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
plugins: ['docusaurus-plugin-sass'],
|
||||
|
|
@ -159,8 +154,7 @@ module.exports = {
|
|||
|
||||
You can now set the `customCss` property of `@docusaurus/preset-classic` to point to your Sass/SCSS file:
|
||||
|
||||
```jsx {9}
|
||||
// docusaurus.config.js
|
||||
```jsx {8} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
presets: [
|
||||
[
|
||||
|
|
@ -181,8 +175,7 @@ module.exports = {
|
|||
|
||||
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.
|
||||
|
||||
```scss
|
||||
/* styles.module.scss */
|
||||
```scss title="styles.module.scss"
|
||||
.main {
|
||||
padding: 12px;
|
||||
|
||||
|
|
|
|||
|
|
@ -15,8 +15,7 @@ This section is a work in progress.
|
|||
|
||||
To remove the ability to switch on dark mode, there is an option `themeConfig.disableDarkMode`, which is implicitly set to `false`.
|
||||
|
||||
```js {5}
|
||||
// docusaurus.config.js
|
||||
```js {4} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
@ -30,8 +29,7 @@ module.exports = {
|
|||
|
||||
You can configure a default image that will be used for your meta tag, in particular `og:image` and `twitter:image`.
|
||||
|
||||
```js {5-7}
|
||||
// docusaurus.config.js
|
||||
```js {4-6} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
@ -51,8 +49,7 @@ You can add a logo and title to the navbar via `themeConfig.navbar`. Logo can be
|
|||
|
||||
To improve dark mode support, you can also set a different logo for this mode.
|
||||
|
||||
```js {6-12}
|
||||
// docusaurus.config.js
|
||||
```js {5-11} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
@ -75,8 +72,7 @@ module.exports = {
|
|||
|
||||
You can add links to the navbar via `themeConfig.navbar.links`:
|
||||
|
||||
```js {6-16}
|
||||
// docusaurus/config.js
|
||||
```js {5-15} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
@ -104,8 +100,7 @@ Outbound links automatically get `target="_blank" rel="noopener noreferrer"` att
|
|||
|
||||
You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.
|
||||
|
||||
```js {6}
|
||||
// docusaurus/config.js
|
||||
```js {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
@ -127,8 +122,7 @@ Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-r
|
|||
|
||||
By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js) as syntax highlighting theme. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes). If you want to use a different syntax highlighting theme when the site is in dark mode, you may also do so.
|
||||
|
||||
```js {5,6}
|
||||
// docusaurus/config.js
|
||||
```js {4-5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
prism: {
|
||||
|
|
@ -145,8 +139,7 @@ module.exports = {
|
|||
|
||||
You can set a default language for code blocks if no language is added after the opening triple backticks (i.e. ```). Note that a valid [language name](https://prismjs.com/#supported-languages) must be passed, e.g.:
|
||||
|
||||
```js {6}
|
||||
// docusaurus/config.js
|
||||
```js {5} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
...
|
||||
themeConfig: {
|
||||
|
|
|
|||
|
|
@ -15,8 +15,7 @@ npm install --save docusaurus-plugin-name
|
|||
|
||||
Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
|
||||
|
||||
```jsx {4}
|
||||
// docusaurus.config.js
|
||||
```jsx {3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: ['@docusaurus/plugin-content-pages'],
|
||||
|
|
@ -25,8 +24,7 @@ module.exports = {
|
|||
|
||||
Docusaurus can also load plugins from your local directory, you can do something like the following:
|
||||
|
||||
```jsx {6}
|
||||
// docusaurus.config.js
|
||||
```jsx {5} title="docusaurus.config.js"
|
||||
const path = require('path');
|
||||
|
||||
module.exports = {
|
||||
|
|
@ -41,8 +39,7 @@ For the most basic usage of plugins, you can provide just the plugin name or the
|
|||
|
||||
However, plugins can have options specified by wrapping the name and an options object in an array inside your config. This style is usually called `Babel Style`.
|
||||
|
||||
```js {5-10}
|
||||
// docusaurus.config.js
|
||||
```js {4-9} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
plugins: [
|
||||
|
|
@ -58,8 +55,7 @@ module.exports = {
|
|||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
// Basic usage.
|
||||
|
|
@ -88,8 +84,7 @@ A plugin is a module which exports a function that takes two parameters and retu
|
|||
|
||||
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).
|
||||
|
||||
```js
|
||||
// my-docusaurus-plugin.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = function(context, options) {
|
||||
// ...
|
||||
return {
|
||||
|
|
@ -143,8 +138,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
|
|||
|
||||
:::
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
|
|
@ -213,8 +207,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
|
|||
|
||||
:::
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
|
|
@ -282,8 +275,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
|
|||
|
||||
:::
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
[
|
||||
|
|
@ -325,8 +317,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
|
|||
|
||||
**Configuration**
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: ['@docusaurus/plugin-google-analytics'],
|
||||
themeConfig: {
|
||||
|
|
@ -357,8 +348,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
|
|||
|
||||
**Configuration**
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: ['@docusaurus/plugin-google-gtag'],
|
||||
themeConfig: {
|
||||
|
|
@ -387,8 +377,7 @@ If you have installed `@docusaurus/preset-classic`, you don't need to install it
|
|||
|
||||
:::
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
plugins: [
|
||||
'@docusaurus/plugin-sitemap',
|
||||
|
|
|
|||
|
|
@ -9,8 +9,7 @@ Like plugins, themes are designed to add functionality to your Docusaurus site.
|
|||
|
||||
To use themes, specify the themes in your `docusaurus.config.js`. You may use multiple themes:
|
||||
|
||||
```js {4}
|
||||
// docusaurus.config.js
|
||||
```js {3} title="docusaurus.config.js"
|
||||
module.exports = {
|
||||
// ...
|
||||
themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
|
||||
|
|
@ -52,8 +51,7 @@ website
|
|||
|
||||
For example, a Docusaurus blog consists of a blog plugin and a blog theme.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
{
|
||||
theme: ['theme-blog'],
|
||||
plugins: ['plugin-content-blog'],
|
||||
|
|
@ -62,8 +60,7 @@ For example, a Docusaurus blog consists of a blog plugin and a blog theme.
|
|||
|
||||
and if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (fictitious non-existing theme):
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
```js title="docusaurus.config.js"
|
||||
{
|
||||
theme: ['theme-blog-bootstrap'],
|
||||
plugins: ['plugin-content-blog'],
|
||||
|
|
|
|||
|
|
@ -167,7 +167,7 @@ module.exports = function(context, options) {
|
|||
};
|
||||
```
|
||||
|
||||
## postBuild(props)
|
||||
## `postBuild(props)`
|
||||
|
||||
Called when a (production) build finishes.
|
||||
|
||||
|
|
|
|||
|
|
@ -172,7 +172,7 @@ module.exports = function(context, options) {
|
|||
};
|
||||
```
|
||||
|
||||
## postBuild(props)
|
||||
## `postBuild(props)`
|
||||
|
||||
Called when a (production) build finishes.
|
||||
|
||||
|
|
|
|||
|
|
@ -176,7 +176,7 @@ module.exports = function(context, options) {
|
|||
};
|
||||
```
|
||||
|
||||
## postBuild(props)
|
||||
## `postBuild(props)`
|
||||
|
||||
Called when a (production) build finishes.
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue