More doc improvements (#532)

* Generic doc improvements

* Convert to Markdown

* Remove whitespace

* More typo fixes

docs/api-commands.md

@@ -74,7 +74,7 @@ Alias: `publish-gh-pages`
 
 [Builds](api-commands.md#docusaurus-build), then deploys the static website to GitHub Pages. This command is meant to be run during the deployment step in Circle CI, and therefore expects a few environment variables to be defined:
 
-The following is generally set manually by the user in the CircleCI `config.yml` file.
+The following environment variables are generally set manually by the user in the CircleCI `config.yml` file.
 
  - `GIT_USER`: The git user to be associated with the deploy commit.
  - `USE_SSH`: Whether to use SSH instead of HTTPS for your connection to the GitHub repo.
@@ -85,15 +85,15 @@ The following is generally set manually by the user in the CircleCI `config.yml`
  GIT_USER=docusaurus-bot USE_SSH=true yarn run publish-gh-pages
  ```
 
-The following are set by the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/) during the build process.
+The following environment variables are [set by CircleCI](https://circleci.com/docs/1.0/environment-variables/) during the build process.
 
  - `CIRCLE_BRANCH`: The git branch associated with the commit that triggered the CI run.
  - `CI_PULL_REQUEST`: Expected to be truthy if the current CI run was triggered by a commit in a pull request.
 
 The following should be set by you in `siteConfig.js` as `organizationName` and `projectName`, respectively. If they are not set in your site configuration, they fall back to the [CircleCI environment](https://circleci.com/docs/1.0/environment-variables/).
 
- - `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the git repo, e.g. "facebook".
+ - `CIRCLE_PROJECT_USERNAME`: The GitHub username or organization name that hosts the Git repo, e.g. "facebook".
- - `CIRCLE_PROJECT_REPONAME`: The name of the git repo, e.g. "Docusaurus".
+ - `CIRCLE_PROJECT_REPONAME`: The name of the Git repo, e.g. "Docusaurus".
 
 You can learn more about configuring automatic deployments with CircleCI in the [Publishing guide](getting-started-publishing.md).
 

docs/getting-started-publishing.md

@@ -82,7 +82,7 @@ If you haven't done so already, you can [setup CircleCI](https://circleci.com/si
 1. Go to https://github.com/settings/tokens for the `GIT_USER` and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/), granting it full control of private repositories through the `repo` access scope. Store this token in a safe place, making sure to not share it with anyone. This token can be used to authenticate GitHub actions on your behalf in place of your GitHub password.
 1. Open your Circle CI dashboard, and navigate to the Settings page for your repository, then select "Environment variables". The URL looks like https://circleci.com/gh/ORG/REPO/edit#env-vars, where "ORG/REPO" should be replaced with your own GitHub org/repo.
 1. Create a new environment variable named `GITHUB_TOKEN`, using your newly generated access token as the value.
-1. Create a `.circleci` folder and create a `config.yml` under that folder. 
+1. Create a `.circleci` folder and create a `config.yml` under that folder.
 1. Copy the text below into `.circleci/config.yml`.
 
 ```yml
@@ -104,7 +104,7 @@ jobs:
 
     steps:
       - checkout
-      - run: 
+      - run:
           name: Deploying to GitHub Pages
           command: |
             git config --global user.email "<GITHUB_USERNAME>@users.noreply.github.com"
@@ -132,7 +132,7 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
 
 > If you would rather use a deploy key instead of a personal access token, you can by starting with the Circle CI [instructions](https://circleci.com/docs/1.0/adding-read-write-deployment-key/) for adding a read/write deploy key.
 
-#### Tips & Tricks
+### Tips & Tricks
 
 When initially deploying to a `gh-pages` branch using Circle CI, you may notice that some jobs triggered by commits to the `gh-pages` branch fail to run successfully due to a lack of tests. You can easily work around this by creating a basic Circle CI config with the following contents:
 

docs/guides-navigation.md

@@ -163,14 +163,14 @@ headerLinks: [
 
 The links in the top navigation bar get `siteNavItemActive` and `siteNavGroupActive` class names to allow you to style the currently active link different from the others. `siteNavItemActive` is applied when there's an exact match between the navigation link and the currently displayed web page.
 
-> This does not include links of type `href` which are meant for external links only. If you manually set an `href` in your headerLinks to an internal page, document, or blog post, it will not get the `siteNavItemActive` class even if that page is being displayed.
+> This does not include links of type `href` which are meant for external links only. If you manually set an `href` in your `headerLinks` to an internal page, document, or blog post, it will not get the `siteNavItemActive` class even if that page is being displayed.
 
-`siteNavGroupActive` will be added to these links:
+The `siteNavGroupActive` class will be added to these links:
 
 * `doc` links that belong to the same sidebar as the currently displayed document
 * The blog link when a blog post, or the blog listing page is being displayed
 
-These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same css rule.
+These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.
 
 ## Secondary On-Page Navigation
 

docs/guides-search.md

@@ -29,9 +29,9 @@ const siteConfig = {
   ...
   algolia: {
     ...
-    algoliaOptions: { 
+    algoliaOptions: {
-      facetFilters: [ "tags:VERSION" ], 
+      facetFilters: [ "tags:VERSION" ],
-      hitsPerPage: 5 
+      hitsPerPage: 5
     }
   },
 }

docs/guides-translation.md

@@ -116,9 +116,9 @@ For other pages, Docusaurus will automatically transform all `<translate>` tags
 
 ## Crowdin
 
-Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations
+Crowdin is a company that provides translation services. For Open Source projects, Crowdin provides free string translations.
 
-Create your translation project on [Crowdin](https://crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow. _We suggest that you deselect and do not include "English" as a translateable language to prevent the creation of `en-US` localization files as this can lead to confusion._
+Create your translation project on [Crowdin](https://crowdin.com/). You can use [Crowdin's guides](https://support.crowdin.com/translation-process-overview/) to learn more about the translations work flow. _We suggest that you deselect and do not include "English" as a translatable language to prevent the creation of `en-US` localization files as this can lead to confusion._
 
 > Ensure in your Crowdin settings, in the Translations section, that "Duplicate Strings" are set to ["Hide - all duplicates will share the same translation"](https://support.crowdin.com/api/create-project/). This setting will ensure that identical strings between versions share a single translation.
 
@@ -128,7 +128,7 @@ Your project will need a `crowdin.yaml` file generated. If you ran `yarn example
 
 The example below can be automatically generated by the Docusaurus cli with the `examples` script. It should be placed in the top level of your project directory to configure how and what files are uploaded/downloaded.
 
-Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Behasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.
+Below is an example Crowdin configuration for the respective languages: German, Spanish, French, Japanese, Korean, Bahasa Indonesia, Portuguese Brazilian, Chinese Simplified, and Chinese Traditional.
 
 ```yaml
 project_identifier_env: CROWDIN_DOCUSAURUS_PROJECT_ID
@@ -157,9 +157,9 @@ You can go [here](https://support.crowdin.com/configuration-file/) to learn more
 
 ### Setup the Crowdin Scripts
 
-You will want to manually sync your files to and from crowdin. The sync process will upload any markdown files in `/docs` as well as translatable strings in `website/i18n/en.json`. (These strings can be generated by running `yarn write-translations`.)
+You will want to manually sync your files to and from Crowdin. The sync process will upload any markdown files in `/docs` as well as translatable strings in `website/i18n/en.json`. (These strings can be generated by running `yarn write-translations`.)
 
-You can add the following to your `package.json` to manually trigger crowdin.
+You can add the following to your `package.json` to manually trigger Crowdin.
 
 ```json
 "scripts": {
@@ -179,7 +179,7 @@ CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY
 
 > `YOUR_CROWDIN_PROJECT_ID` is the name of your Crowdin project. e.g., for https://crowdin.com/project/docusaurus/, that variable would be set to `docusaurus`. `YOUR_CROWDIN_API_KEY` is a unique key that is like a password. You can find it in the `API` tab of your Crowdin project's `Settings`.
 
-> These commands require having an environment variable set with your crowdin project id and api key (`CROWDIN_PROJECT_ID`, `CROWDIN_API_KEY`). You can preface them inline as done above or add them permanently to your `.bashrc` or `.bash_profile`.
+> These commands require having an environment variable set with your Crowdin project id and api key (`CROWDIN_PROJECT_ID`, `CROWDIN_API_KEY`). You can preface them inline as done above or add them permanently to your `.bashrc` or `.bash_profile`.
 
 > If you run more than one localized Docusaurus project on your computer, you should change the name of the environment variables to something unique (`CROWDIN_PROJECTNAME_PROJECT_ID`, `CROWDIN_PROJECTNAME_API_KEY`).
 

docs/guides-versioning.md

@@ -53,7 +53,7 @@ You can create version numbers in whatever format you wish, and a new version ca
 
 Versioned documents are placed into `website/versioned_docs/version-${version}`, where `${version}` is the version number you supplied the `version` script.
 
-The markdown header for each versioned doc is altered by renaming the id frontmatter field to `original_id`, then using `"version-${version}-${original_id}"` as the value for the actual `id` field.
+The markdown header for each versioned doc is altered by renaming the id front matter field to `original_id`, then using `"version-${version}-${original_id}"` as the value for the actual `id` field.
 
 Versioned sidebars are copied into `website/versioned_sidebars` and are named as `version-${version}-sidebars.json`.
 

lib/server/translation.js

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-// translation object contains all translations for each string in 18n/en.json
+// translation object contains all translations for each string in i18n/en.json
 
 const CWD = process.cwd();
 const fs = require('fs');

website/pages/en/index.js

@@ -230,7 +230,7 @@ class Index extends React.Component {
                 contents={[
                   {
                     content:
-                      "<i>I’ve helped open source many projects at Facebook and every one needed a website. They all had very similar constraints: the documentation should be written in markdown and be deployed via GitHub pages. None of the existing solutions were great, so I hacked my own and then forked it whenever we needed a new website. I’m so glad that Docusaurus now exists so that I don’t have to spend a week each time spinning up a new one.</i>",
+                      "*I've helped open source many projects at Facebook and every one needed a website. They all had very similar constraints: the documentation should be written in markdown and be deployed via GitHub pages. None of the existing solutions were great, so I hacked my own and then forked it whenever we needed a new website. I’m so glad that Docusaurus now exists so that I don’t have to spend a week each time spinning up a new one.*",
                     image: `${siteConfig.baseUrl}img/christopher-chedeau.jpg`,
                     imageAlign: "top",
                     imageAlt: 'Christopher "vjeux" Chedeau',
@@ -238,7 +238,7 @@ class Index extends React.Component {
                   },
                   {
                     content:
-                      "<i>Open source contributions to the React Native docs have skyrocketed after our move to Docusaurus. The docs are now hosted on a small repo in plain markdown, with none of the clutter that a typical static site generator would require. Thanks Slash!</i>",
+                      "*Open source contributions to the React Native docs have skyrocketed after our move to Docusaurus. The docs are now hosted on a small repo in plain markdown, with none of the clutter that a typical static site generator would require. Thanks Slash!*",
                     image: `${siteConfig.baseUrl}img/hector-ramos.png`,
                     imageAlign: "top",
                     imageAlt: "Hector Ramos",
@@ -246,7 +246,7 @@ class Index extends React.Component {
                   },
                   {
                     content:
-                      "<i>Docusaurus has been a great choice for the ReasonML family of projects. It makes our documentation consistent, i18n-friendly, easy to maintain, and friendly for new contributors.</i>",
+                      "*Docusaurus has been a great choice for the ReasonML family of projects. It makes our documentation consistent, i18n-friendly, easy to maintain, and friendly for new contributors.*",
                     image: `${siteConfig.baseUrl}img/ricky-vetter.jpg`,
                     imageAlign: "top",
                     imageAlt: "Ricky Vetter",
@@ -256,7 +256,7 @@ class Index extends React.Component {
                 layout="threeColumn"
               />
             </Container>
-        </div>
+          </div>
         </div>
       </div>
     );