Update custom pages document (#214)

docs/api-pages.md

@@ -22,7 +22,7 @@ If you wish to use your own components inside the website folder, use `process.c
 
 Docusaurus provides the following components in `CompLibrary`:
 
-### `CompLibrary.MarkdownBlock` 
+### `CompLibrary.MarkdownBlock`
 
 A React component that parses markdown and renders to HTML.
 
@@ -51,16 +51,16 @@ Example:
 
 ### `CompLibrary.GridBlock`
 
-A React component to organize text and images. 
+A React component to organize text and images.
 
 The `align` attribute determines text alignment. Text alignment defaults to `left` and can be set to `center` or `right`.
 
 The `layout` attribute determines number of column sections per GridBlock. `layout` defaults to `twoColumn` and can be set to `threeColumn` or `fourColumn` as well.
 
-The `contents` attribute is an array containing the contents of each section of the GridBlock. Each content object can have the following fields: 
+The `contents` attribute is an array containing the contents of each section of the GridBlock. Each content object can have the following fields:
 
 - `content` for the text of this section, which is parsed from markdown
-- `image` for the path to an image to display 
+- `image` for the path to an image to display
 - `imageAlign` field for image alignment relative to the text, which defaults to `top` and can be set to `bottom`, `left`, or `right`
 - `title` for the title to display for this section, which is parsed from markdown
 - `imageLink` for a link destination from clicking the image
@@ -132,9 +132,3 @@ You should configure your site's primary, secondary, and code block colors using
 You can provide your own custom styles by adding them anywhere in the `website/static` folder. Any `.css` files you provide in the `static` folder will get concatenated to the end of Docusaurus's provided styles, allowing you to add to or override Docusaurus default styles as you wish.
 
 An easy way to figure out what classes you wish to override or add to is to [start your server locally](api-commands.md) and use your browser's inspect element tool.
-
-## Adding Static Pages
-
-Static `.html` files can also be used, but they will not include Docusaurus's header, footer, or styles by default. These can be added to the `static` folder in the same way as other static assets. Alternatively, they can be placed in the `pages` folder and would be served as-is instead of being rendered from React.
-
-If you wish to use Docusaurus's stylesheet, you can access it at `${baseUrl}css/main.css`. If you wish to use separate css for these static pages, you can exclude them from being concatenated to Docusaurus's styles by adding them into the `siteConfig.separateCss` field.

docs/guides-custom-pages.md

@@ -3,17 +3,47 @@ id: custom-pages
 title: Custom Pages
 ---
 
+You can add pages to your site that are not part of the standard docs or blog markdown files. You can do this by adding `.js` files to the `website/pages` directory. These files are React components and the `render()` is called to create them, backed by CSS classes, etc.
+
 ## Customizing Your Home Page
 
-The easiest way to get started customizing your home page is to use the [examples generated previously](getting-started-site-creation.md). You can start your local server and go to `http://localhost:3000` to see what the example home page looks like. From there, edit the `website/pages/en/index.js` file and its various components to use the images and text you want for your project.
+The easiest way to get started customizing your home page is to use the example site that was [created](getting-started-site-creation.md) when you ran the [Docusaurus initialization script](getting-started-installation.md).
+
+You can [start](site-preparation.md#verifying-installation) your local server and go to `http://localhost:3000` to see what the example home page looks like. From there, edit the `website/pages/en/index.js` file and its various components to use the images and text you want for your project.
 
 ## Adding Other Custom Pages
 
-Docusaurus provides some simple example pages (`index.js`, `users.js`, `help.js`), but of course you're also free to write your own pages however you want. It is strongly suggested that you at least have an index page, but none of the pages are mandatory to include. More information on how to use the provided components or include your own can be found [here](api-pages.md). Information on how to link to your different pages in the header navigation bar can be found [here](guides-navigation.md).
+Docusaurus provides some simple example pages in the `website/pages/en` directory, including `index.js`, `users.js`, and `help.js`. These are good examples to showcase how to create a custom page for Docusaurus.
+
+```bash
+root-of-repo
+├── docs
+└── website
+│   └── blog
+│   └── core
+│       └── Footer.js
+│   └── node_modules
+│   └── package.json
+│   └── pages
+│       └── index.js
+│       └── users.js
+│       └── help.js
+│   └── sidebars.json
+│   └── siteConfig.js
+│   └── static
+```
+
+Of course, you are also free to write your own pages. It is strongly suggested that you at least have an index page, but none of the pages provided are mandatory to include in your site. More information on how to use the provided components or include your own can be found [here](api-pages.md). Information on how to link to your different pages in the header navigation bar can be found [here](guides-navigation.md).
+
+## Adding Static Pages
+
+Static `.html` files can also be used, but they will not include Docusaurus's header, footer, or styles by default. These can be added to the `static` folder in the same way as other [static assets](api-pages.md#using-static-assets). Alternatively, they can be placed in the `pages` folder and would be served as-is instead of being rendered from React.
+
+If you wish to use Docusaurus's stylesheet, you can access it at `${baseUrl}css/main.css`. If you wish to use separate css for these static pages, you can exclude them from being concatenated to Docusaurus's styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`.
 
 ## Customizing Your Site Footer
 
-Starting from the example `core/Footer.js` file you [generated before](getting-started-site-creation.md), edit the footer to include any links to pages on your site or elsewhere that you wish to have. 
+Starting from the example `core/Footer.js` file that was [created](getting-started-site-creation.md) when you ran the [Docusaurus initialization script](getting-started-installation.md), edit the footer to include any links to pages on your site or other sites that you wish to have.
 
 The example provided has three columns with a footer image on the left and Facebook's open source logo and copyright at the bottom. If your project is not a Facebook open source project, remove the logo and copyright. Otherwise, feel free to get creative with your footer and make it look however you'd like!
 
@@ -21,7 +51,8 @@ Some suggestions for links you may want to provide: documentation, API, Twitter,
 
 Your footer will automatically get applied to all pages on your site, including docs and blog posts. The sole exception to this is any static html pages you include.
 
-If you don't want a footer for your site, change the `render` function of `core/Footer.js` to return `null`. e.g.,
+If you do not want a footer for your site, change the `render` function of `core/Footer.js` to return `null`. e.g.,
+
 ```jsx
 const React = require("react");