3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-06-01 10:22:30 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs(v2): update config docs (#1885)

Browse source
This commit is contained in:
Endi 2019-10-25 23:35:02 +07:00 • committed by GitHub
parent a149f775ad
commit a9f752cf23
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 34 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

39
website/docs/configuration.md
View file

@ -7,39 +7,37 @@ 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 easily customize fields. 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 easily customize fields.
For reference to each of the configurable fields, you may refer to the API reference of [docusaurus.config.js](docusaurus.config.js.md).
## What goes into `docusaurus.config.js`? ## What goes into `docusaurus.config.js`?
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` at root that includes the necessary data for the initial site. 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` at root that includes the necessary data for the initial site.
However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented. However, it can be helpful if you have a high-level understanding of how the configurations are designed and implemented.
The configurations can be categorized into: The high-level overview of Docusaurus configuration can be categorized into:
- [Site Metadata](#site-metadata) - [Site Metadata](#site-metadata)
- [Deployment Configurations](#deployment-configurations) - [Deployment Configurations](#deployment-configurations)
- [Themes, Plugins, and Presets configurations](#themes-plugins-and-presets-configurations) - [Themes, Plugins, and Presets configurations](#themes-plugins-and-presets-configurations)
- [Custom Configurations](#custom-configurations) - [Custom Configurations](#custom-configurations)
For exact reference to each of the configurable fields, you may refer to [**docusaurus.config.js API reference**](docusaurus.config.js.md).
### Site metadata ### Site metadata
Site metadata contains the essential global metadata such as titles and `favicon`. Site metadata contains the essential global metadata such as `title`, `url`, `baseUrl` and `favicon`.
They are used by your website in a number of places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information and for search engine optimization (SEO). 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 are used when you deploy your site with Docusaurus' `deploy` command. The related fields are: Deployment configurations such as `projectName` and `organizationName` are used when you deploy your site with Docusaurus' `deploy` command.
<!-- TODO: if we use monospace for the field names, they no longer look like a link --> It is recommended to check the [deployment docs](deployment.md) for more information.
<!-- TODO: currently these fields are only used in GH Pages, what about other deployment services such as Netlify -->
You may also check the [deployment docs](deployment.md) for more information about the fields.
### Themes, Plugins, and Presets configurations ### Themes, Plugins, and Presets configurations
_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._ _This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
<!-- <!--
@ -73,27 +71,20 @@ module.exports = {
## 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 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`.
Basic Example:
```jsx ```jsx
import React from 'react'; import React from 'react';
import Head from '@docusaurus/Head';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
const Layout = props => { const Hello = () => {
const context = useDocusaurusContext(); const context = useDocusaurusContext();
const {siteConfig = {}} = context; const {siteConfig = {}} = context;
const {title, tagline, seo} = siteConfig; const {title, tagline} = siteConfig;
return ( return <div>{`${title} · ${tagline}`}</div>;
<React.Fragment>
<Head defaultTitle={`${defaultTitle} · ${tagline}`}>
{description && <meta name="description" content={seo.description} />}
</Head>
<h1>{title}</h1>
<h2>{tagline}</h2>
</React.Fragment>
);
}; };
``` ```

33
website/docs/docusaurus.config.js.md
View file

@ -1,13 +1,9 @@
--- ---
id: docusaurus.config.js id: docusaurus.config.js
title: docusaurus.config.js title: docusaurus.config.js
description: API reference for Docusaurus configuration file.
--- ---
<!--
Goal: To serve as a manual for all configurations in docusaurus.config.js
Should keep the titles to themselves for cleaner link
-->
## 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.
@ -18,7 +14,7 @@ title: docusaurus.config.js
- Type: `string` - Type: `string`
Title is used in a number of places in your site including the title for the web page, headings, etc. Title for your website.
```js ```js
// docusaurus.config.js // docusaurus.config.js
@ -31,7 +27,7 @@ module.exports = {
- Type: `string` - Type: `string`
Tagline is used in a number of places in your site including the title for the web page, sub headings, etc. The tagline for your website.
```js ```js
// docusaurus.config.js // docusaurus.config.js
@ -45,7 +41,16 @@ module.exports = {
- Type: `string` - Type: `string`
If you use an official template, your site will be generated with the following directory URL for site favicon. Example:
```js
// docusaurus.config.js
module.exports = {
favicon: 'https://v2.docusaurus.io/favicon.ico',
};
```
You can also use the favicon URL relative to the `static` directory of your site. For example, your site has the following directory structure:
```bash ```bash
. .
@ -56,7 +61,7 @@ If you use an official template, your site will be generated with the following
└── favicon.ico └── favicon.ico
``` ```
And your generated `docusaurus.config.js` will contain this the field for your favicon URL relative to the `static` directory of your site. So you can refer it like below:
```js ```js
// docusaurus.config.js // docusaurus.config.js
@ -65,15 +70,11 @@ module.exports = {
}; };
``` ```
**Note**: It does accept external nor absolute url.
### `url` ### `url`
<!-- TODO: where else is this used other than GH Pages? -->
- Type: `string` - Type: `string`
If you use GitHub Pages, this will be the URL for your GitHub Page's user/organization page, commonly https://_username_.github.io. 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 ```js
// docusaurus.config.js // docusaurus.config.js
@ -86,7 +87,7 @@ module.exports = {
- Type: `string` - Type: `string`
Base URL for your project. For projects hosted on GitHub pages, it follows the format "/_projectName_/". For https://github.com/facebook/docusaurus, `baseUrl` is `/docusaurus/`. 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 ```js
// docusaurus.config.js // docusaurus.config.js
@ -147,6 +148,8 @@ An object containing data needed by the theme you use.<!--, see [theme configura
For Docusaurus' default theme _classic_, we use `themeConfig` to customize your navbar and footer links: For Docusaurus' default theme _classic_, we use `themeConfig` to customize your navbar and footer links:
Example:
```js ```js
// docusaurus.config.js // docusaurus.config.js
module.exports = { module.exports = {

2
website/docs/installation.md
View file

@ -7,7 +7,7 @@ Docusaurus is essentially a set of npm [packages](https://github.com/facebook/do
## Requirements ## Requirements
- [Node.js](https://nodejs.org/en/download/) version 8 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 >= 8.9 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