mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 16:59:06 +02:00
docs(v2): Configuration (#1539)
* docs(v2): Configuration * Revamp docs for configurations * Move configuration guide to a lower position on the sidebar * Use filename links inside md * Wrap up configuration docs * Update docusaurus.config.js.md
This commit is contained in:
Wei Gao
Endi
parent
8743ee5041
commit
5af8cd566e
3 changed files with 316 additions and 8 deletions
|
|
@ -3,8 +3,103 @@ id: configuration
|
|||
title: Configuration
|
||||
---
|
||||
|
||||
TODO: Cover the mandatory configuration options here.
|
||||
<!-- Goal: To explain the intention and best practices for configurations -->
|
||||
|
||||
#### References
|
||||
Docusaurus has a unique take on configurations. We encourage you to congregate information of your site into one place. We will guard the fields of this file, and facilitate making this data object accessible across your site.
|
||||
|
||||
- https://v1.vuepress.vuejs.org/guide/basic-config.html
|
||||
Keeping a well-maintained `docusaurus.config.js` helps you, your collaborators, and your open source contributors be able to focus on docs while having certain fields easy to customize.
|
||||
|
||||
For reference to each of the configurable fields, you may refer to the API reference of [docusaurus.config.js](/docs/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.
|
||||
|
||||
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:
|
||||
|
||||
- [Site meta](#site-meta)
|
||||
- [Deployment configurations](#deployment-configurations)
|
||||
- [Theme configurations, plugins, and presets](#theme-plugins-and-presets-configurations)
|
||||
- [Custom configurations](#custom-configurations)
|
||||
|
||||
### Site meta
|
||||
|
||||
Site meta contains the essential meta information such as titles and `favicon`.
|
||||
|
||||
They are used by your site app in a number of places such as your site's title and headings, browser tab icon, and SEO.
|
||||
|
||||
- [title](docusaurus.config.js.md#title)
|
||||
- [tagline](docusaurus.config.js.md#tagline)
|
||||
- [favicon](docusaurus.config.js.md#favicon)
|
||||
|
||||
### Deployment configurations
|
||||
|
||||
Deployment configurations are used when you deploy your site with Docusaurus' deploy command. The related fields are:
|
||||
|
||||
<!-- TODO: if we use monospace for the field names, they no longer look like a link -->
|
||||
|
||||
<!-- TODO: currently these fields are only used in GH Pages, what about other deployment services such as Netlify -->
|
||||
|
||||
- [url](docusaurus.config.js.md#url)
|
||||
- [baseUrl](docusaurus.config.js.md#baseUrl)
|
||||
- [organizationName](docusaurus.config.js.md#organizationname)
|
||||
- [projectName](docusaurus.config.js.md#projectName)
|
||||
|
||||
You may also check the doc for [Deployment](deployment.md) for more information about the fields.
|
||||
|
||||
### Theme, plugins, and presets configurations
|
||||
|
||||
<!-- TODO: More explanation from these docs, respectively -->
|
||||
|
||||
- [themeConfig](docusaurus.config.js.md#themeConfig)
|
||||
- [presets](docusaurus.config.js.md#presets)
|
||||
- [plugins](docusaurus.config.js.md#plugins)
|
||||
|
||||
### Custom configurations
|
||||
|
||||
You may have your own custom fields. And `docusaurus.config.js` will be aware of the fields and guard your configuration from unknown fields.
|
||||
|
||||
- [customFields](docusaurus.config.js.md#customFields)
|
||||
|
||||
To add a custom field, add the field name to `customFields`. Then, you may use the field for your customization data:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
customFields: ['seo'],
|
||||
seo: {
|
||||
image: '',
|
||||
keywords: [],
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
## Accessing configuration from your site
|
||||
|
||||
Your configuration object will be made available to all the components of your site. And you may access them via context as `siteConfig`:
|
||||
|
||||
```jsx
|
||||
import React from 'react';
|
||||
import Head from '@docusaurus/Head';
|
||||
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
|
||||
|
||||
const Layout = props => {
|
||||
const context = useDocusaurusContext();
|
||||
const {siteConfig = {}} = context;
|
||||
const {title, tagline, seo} = siteConfig;
|
||||
return (
|
||||
<React.Fragment>
|
||||
<Head defaultTitle={`${defaultTitle} · ${tagline}`}>
|
||||
{description && <meta name="description" content={seo.description} />}
|
||||
</Head>
|
||||
<h1>{title}</h1>
|
||||
<h2>{tagline}</h2>
|
||||
</React.Fragment>
|
||||
);
|
||||
};
|
||||
```
|
||||
|
||||
## Customized configurations
|
||||
|
|
|
|||
|
|
@ -3,9 +3,222 @@ id: docusaurus.config.js
|
|||
title: docusaurus.config.js
|
||||
---
|
||||
|
||||
TODO: Explain the various `docusaurus.config.js` options.
|
||||
<!--
|
||||
Goal: To serve as a manual for all configurations in docusaurus.config.js
|
||||
Should keep the titles to themselves for cleaner link
|
||||
-->
|
||||
|
||||
#### References
|
||||
## Overview
|
||||
|
||||
- https://docusaurus.io/docs/en/site-config
|
||||
- https://v1.vuepress.vuejs.org/config/
|
||||
`docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
|
||||
|
||||
## Required fields
|
||||
|
||||
### `title`
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Title is used in a number of places in your site including the title for the web page, headings, etc.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
title: 'Docusaurus',
|
||||
};
|
||||
```
|
||||
|
||||
### `tagline`
|
||||
|
||||
- Type: `string`
|
||||
|
||||
Tagline is used in a number of places in your site including the title for the web page, sub headings, etc.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
tagline:
|
||||
'Docusaurus makes it easy to maintain Open Source documentation websites.',
|
||||
};
|
||||
```
|
||||
|
||||
### `favicon`
|
||||
|
||||
- Type: `string`
|
||||
|
||||
If you use an official template, your site will be generated with the following directory
|
||||
|
||||
```bash
|
||||
.
|
||||
├── README.md
|
||||
├ # ... other files in root directory
|
||||
└─ static
|
||||
└── img
|
||||
└── 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.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
favicon: 'img/favicon.ico',
|
||||
};
|
||||
```
|
||||
|
||||
**Note**: It does accept external nor absolute url.
|
||||
|
||||
### `url`
|
||||
|
||||
<!-- TODO: where else is this used other than GH Pages? -->
|
||||
|
||||
- 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.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
url: 'https://docusaurus.io',
|
||||
};
|
||||
```
|
||||
|
||||
### `baseUrl`
|
||||
|
||||
- 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/`.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
baseUrl: '/',
|
||||
};
|
||||
```
|
||||
|
||||
## Optional fields
|
||||
|
||||
### `organizationName`
|
||||
|
||||
- Type: `string`
|
||||
|
||||
The GitHub user or organization that owns the repository.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
// Docusaurus's organization is facebook
|
||||
organizationName: 'facebook',
|
||||
};
|
||||
```
|
||||
|
||||
### `projectName`
|
||||
|
||||
- Type: `string`
|
||||
|
||||
The name of the GitHub repository.
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
projectName: 'docusaurus',
|
||||
};
|
||||
```
|
||||
|
||||
### `themeConfig`
|
||||
|
||||
- Type: `Object`
|
||||
|
||||
<!-- TODO: explain that theme configurations will be consumed by the theme, and link to theme doc -->
|
||||
|
||||
An object containing data needed by the theme you use.<!--, see [theme configurations](#).-->
|
||||
|
||||
For Docusaurus' default theme _classic_, we use `themeConfig` to customize your navbar and footer links:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
themeConfig: {
|
||||
navbar: {
|
||||
title: 'Site Title',
|
||||
logo: {
|
||||
alt: 'Site Logo',
|
||||
src: 'img/logo.svg',
|
||||
},
|
||||
links: [
|
||||
{
|
||||
to: 'docs/docusaurus.config.js',
|
||||
label: 'docusaurus.config.js',
|
||||
position: 'left',
|
||||
},
|
||||
// ... other links
|
||||
],
|
||||
},
|
||||
footer: {
|
||||
style: 'dark',
|
||||
links: [
|
||||
{
|
||||
title: 'Docs',
|
||||
items: [
|
||||
{
|
||||
label: 'Docs',
|
||||
to: 'docs/doc1',
|
||||
},
|
||||
],
|
||||
},
|
||||
// ... other links
|
||||
],
|
||||
logo: {
|
||||
alt: 'Facebook Open Source Logo',
|
||||
src: 'https://docusaurus.io/img/oss_logo.png',
|
||||
},
|
||||
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
### `plugins`
|
||||
|
||||
<!-- TODO: configuration for plugins -->
|
||||
|
||||
- Type: `any[]`
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
plugins: [],
|
||||
};
|
||||
```
|
||||
|
||||
### `presets`
|
||||
|
||||
<!-- TODO: configuration for presets -->
|
||||
|
||||
- Type: `any[]`
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
presets: [],
|
||||
};
|
||||
```
|
||||
|
||||
### `customFields` and other custom fields
|
||||
|
||||
Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom field, add the field name to `customFields`, then add the field to the module.
|
||||
|
||||
- Type: `string[]`
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
customFields: ['seo'],
|
||||
seo: // ... the actual custom field
|
||||
};
|
||||
```
|
||||
|
||||
Attempting to add custom fields without indicating in `customFields` will lead to error in build time:
|
||||
|
||||
```bash
|
||||
Error: The field(s) 'foo', 'bar' are not recognized in docusaurus.config.js
|
||||
```
|
||||
|
|
|
|||
|
|
@ -15,7 +15,6 @@ module.exports = {
|
|||
'deployment',
|
||||
],
|
||||
Guides: [
|
||||
'configuration',
|
||||
'assets',
|
||||
'markdown',
|
||||
'styling-layout',
|
||||
|
|
@ -23,6 +22,7 @@ module.exports = {
|
|||
'using-themes',
|
||||
'search',
|
||||
'analytics',
|
||||
'configuration',
|
||||
],
|
||||
'Advanced Guides': ['blog', 'plugins', 'themes', 'presets'],
|
||||
'API Reference': [
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue