mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-31 01:47:17 +02:00
docs(v2): update config docs (#1885)
This commit is contained in:
Endi
GitHub
parent
a149f775ad
commit
a9f752cf23
3 changed files with 34 additions and 40 deletions
|
|
@ -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.
|
||||
|
||||
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`?
|
||||
|
||||
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:
|
||||
The high-level overview of Docusaurus configuration can be categorized into:
|
||||
|
||||
- [Site Metadata](#site-metadata)
|
||||
- [Deployment Configurations](#deployment-configurations)
|
||||
- [Themes, Plugins, and Presets configurations](#themes-plugins-and-presets-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 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 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 -->
|
||||
|
||||
<!-- 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.
|
||||
It is recommended to check the [deployment docs](deployment.md) for more information.
|
||||
|
||||
### Themes, Plugins, and Presets configurations
|
||||
|
||||
|
||||
|
||||
_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
|
||||
|
||||
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
|
||||
import React from 'react';
|
||||
import Head from '@docusaurus/Head';
|
||||
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
|
||||
|
||||
const Layout = props => {
|
||||
const Hello = () => {
|
||||
const context = useDocusaurusContext();
|
||||
const {siteConfig = {}} = context;
|
||||
const {title, tagline, seo} = siteConfig;
|
||||
const {title, tagline} = siteConfig;
|
||||
|
||||
return (
|
||||
<React.Fragment>
|
||||
<Head defaultTitle={`${defaultTitle} · ${tagline}`}>
|
||||
{description && <meta name="description" content={seo.description} />}
|
||||
</Head>
|
||||
<h1>{title}</h1>
|
||||
<h2>{tagline}</h2>
|
||||
</React.Fragment>
|
||||
);
|
||||
return <div>{`${title} · ${tagline}`}</div>;
|
||||
};
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,13 +1,9 @@
|
|||
---
|
||||
id: 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
|
||||
|
||||
`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`
|
||||
|
||||
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
|
||||
// docusaurus.config.js
|
||||
|
|
@ -31,7 +27,7 @@ module.exports = {
|
|||
|
||||
- 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
|
||||
// docusaurus.config.js
|
||||
|
|
@ -45,7 +41,16 @@ module.exports = {
|
|||
|
||||
- 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
|
||||
.
|
||||
|
|
@ -56,7 +61,7 @@ If you use an official template, your site will be generated with the following
|
|||
└── 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
|
||||
// docusaurus.config.js
|
||||
|
|
@ -65,15 +70,11 @@ module.exports = {
|
|||
};
|
||||
```
|
||||
|
||||
**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.
|
||||
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
|
||||
|
|
@ -86,7 +87,7 @@ module.exports = {
|
|||
|
||||
- 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
|
||||
// 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:
|
||||
|
||||
Example:
|
||||
|
||||
```js
|
||||
// docusaurus.config.js
|
||||
module.exports = {
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ Docusaurus is essentially a set of npm [packages](https://github.com/facebook/do
|
|||
|
||||
## 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.
|
||||
|
||||
## Scaffold project website
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue