Reformat, proofread and tidy up docs (#749)

This commit is contained in:
Yangshun Tay 2018-06-10 08:02:04 -07:00 committed by Joel Marcey
parent 33a0f309ff
commit 18c01327a3
14 changed files with 200 additions and 212 deletions

View file

@ -12,23 +12,22 @@ After [installation](getting-started-installation.md) and [preparation](getting-
Your site structure looks like the following:
```bash
root-of-repo
root-directory
├── docs
├── website
│ ├── blog
│ ├── core
│ │ └── Footer.js
│ ├── node_modules
│ ├── package.json
│ ├── pages
│ ├── sidebars.json
│ ├── siteConfig.js
│ └── static
└── website
├── blog
├── core
│ └── Footer.js
├── package.json
├── pages
├── sidebars.json
├── siteConfig.js
└── static
```
> This assumes that you removed the example `.md` files that were installed with the [initialization](getting-started-installation.md) script.
All of your documentation files should be placed inside the `docs` folder as markdown `.md` files. Any blog posts should be inside the `blog` folder.
All of your documentation files should be placed inside the `docs` directory as markdown `.md` files. Any blog posts should be inside the `blog` directory.
> The blog posts must be formatted as `YYYY-MM-DD-your-file-name.md`
@ -36,7 +35,7 @@ All of your documentation files should be placed inside the `docs` folder as mar
To create a fully functional site, you only need to do a few steps:
1. Add your documentation to the `/docs` folder as `.md` files, ensuring you have the proper [header](api-doc-markdown.md#documents) in each file. The simplest header would be the following, where `id` is the link name (e.g., `docs/intro.html`) and the `title`, is, of course, the title of the browser page.
1. Add your documentation to the `/docs` directory as `.md` files, ensuring you have the proper [header](api-doc-markdown.md#documents) in each file. The simplest header would be the following, where `id` is the link name (e.g., `docs/intro.html`) and the `title`, is, of course, the title of the browser page.
```yaml
---
@ -47,20 +46,20 @@ To create a fully functional site, you only need to do a few steps:
My new content here..
```
1. Add zero or more docs to the [`sidebars.json`](guides-navigation.md#adding-docs-to-a-sidebar) file so that your documentation is rendered in a sidebar, if you choose them to be.
1. Add zero or more docs to the [`sidebars.json`](guides-navigation.md#adding-docs-to-a-sidebar) file so that your documentation is rendered in a sidebar, if you choose them to be.
> If you do not add your documentation to the `sidebars.json` file, the docs will be rendered, but they can only be linked to from other documentation and visited with the known URL.
> If you do not add your documentation to the `sidebars.json` file, the docs will be rendered, but they can only be linked to from other documentation and visited with the known URL.
3. Modify the `website/siteConfig.js` file to [configure your site](api-site-config.md), following the comments included in the [docs](api-site-config.md) and the `website/siteConfig.js` to guide you.
1. Create any [custom pages](guides-custom-pages.md#customizing-your-site-footer) and/or [customize](guides-custom-pages.md#customizing-your-site-footer) the `website/core/Footer.js` file that provides the footer for your site.
1. Place assets, such as images, in the `website/static/` folder.
1. Run the site to see the results of your changes.
3. Modify the `website/siteConfig.js` file to [configure your site](api-site-config.md), following the comments included in the [docs](api-site-config.md) and the `website/siteConfig.js` to guide you.
1. Create any [custom pages](guides-custom-pages.md#customizing-your-site-footer) and/or [customize](guides-custom-pages.md#customizing-your-site-footer) the `website/core/Footer.js` file that provides the footer for your site.
1. Place assets, such as images, in the `website/static/` directory.
1. Run the site to see the results of your changes.
```bash
cd website
yarn run start # or `npm run start`
# Navigate to http://localhost:3000
```
```bash
cd website
yarn run start # or `npm run start`
# Navigate to http://localhost:3000
```
## Special Customization
@ -68,8 +67,8 @@ To create a fully functional site, you only need to do a few steps:
If you prefer to have your landing page be straight to your documentation, you can do this through a redirect.
1. Remove the `index.js` file from the `website/pages` directory, if it exists.
1. Add a [custom static `index.html` page](guides-custom-pages.md#adding-static-pages) in the `website/static` folder with the following contents:
1. Remove the `index.js` file from the `website/pages` directory, if it exists.
1. Add a [custom static `index.html` page](guides-custom-pages.md#adding-static-pages) in the `website/static` directory with the following contents:
```html
<!DOCTYPE HTML>