Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(v2): update config docs #1885

Merged
merged 1 commit into from
Oct 25, 2019
Merged

docs(v2): update config docs #1885

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 15 additions & 24 deletions website/docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,38 +7,36 @@ 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 -->
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 -->
### Themes, Plugins, and Presets configurations

You may also check the [deployment docs](deployment.md) for more information about the fields.

### Themes, Plugins, and Presets configurations

_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._

Expand Down Expand Up @@ -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 = () => {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Simplify example

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>
);
const {title, tagline} = siteConfig;

return <div>{`${title} · ${tagline}`}</div>;
};
```

Expand Down
33 changes: 18 additions & 15 deletions website/docs/docusaurus.config.js.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Less word is better.

Title for your website.

```js
// docusaurus.config.js
Expand All @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually is this field strictly necessary? If we don't use it in the pages/index it's not used right?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i think not really required, i think we can make it theme-specific. but It is used in theme-fallback layout now (which we can remove). Its only used as default title in @theme/Layout.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

but this PR is only about docs change. I'm gonna take a rest. do you want to remove it from required field of docusaurus.config and make it as themeConfig instead ?

I think we're still missing a doc page for @docusaurus-theme-classic Theme Configuration
It's still not clear what are the fields available. eg: navbar, footer, image


```js
// docusaurus.config.js
Expand All @@ -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
.
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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/`.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I modified this because its not always specific to github pages and can be confusing especially if they use custom domain

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
Expand Down Expand Up @@ -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 = {
Expand Down
2 changes: 1 addition & 1 deletion website/docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down