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

facebook · Oct 25, 2019 · a9f752c · a9f752c
1 parent a149f77
commit a9f752c
Show file tree

Hide file tree

Showing 3 changed files with 34 additions and 40 deletions.
diff --git a/website/docs/configuration.md b/website/docs/configuration.md
@@ -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)._
 
@@ -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;
-
-  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>;
 };
 ```
 

diff --git a/website/docs/docusaurus.config.js.md b/website/docs/docusaurus.config.js.md
@@ -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 = {

diff --git a/website/docs/installation.md b/website/docs/installation.md
@@ -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