Use proper syntax highlighting for code blocks (#615)

* Better syntax highlighting

* Better syntax highlighting

CONTRIBUTING.md

@@ -109,7 +109,7 @@ A good test plan has the exact commands you ran and their output, provides scree
 
 When adding a new breaking change, follow this template in your pull request:
 
-```
+```md
 ### New breaking change here
 
 * **Who does this affect**:
@@ -122,7 +122,7 @@ When adding a new breaking change, follow this template in your pull request:
 
 Copy and paste this to the top of your new file(s):
 
-```JS
+```js
 /**
  * Copyright (c) 2017-present, Facebook, Inc.
  *

admin/extending-remarkable.md

@@ -4,8 +4,8 @@ Docusaurus uses [Remarkable](https://github.com/jonschlinkert/remarkable) to con
 
 Users of GitHub Pages have come to expect certain features provided by GitHub Flavored Markdown. One such example would be heading anchors, where every sub-header has an associated anchor that matches the heading text. This makes it possible to link to a specific section in a document by passing a fragment that matches the heading. For example, to link to this very section, you may create a link like so:
 
-```
+```md
-    [Link to this section](#why-extend-remarkable)
+[Link to this section](#why-extend-remarkable)
 ```
 
 ## A Brief Overview of How A Markdown Parser/Renderer Works
@@ -26,7 +26,7 @@ Inline tokens are simple tokens that have text as a child. They are leaf nodes,
 
 A block token is a bit more complex. It may wrap one or more tokens, and can span more than one line of text. An example of this is the heading token:
 
-```
+```md
 ### Hi there
 ```
 
@@ -52,7 +52,7 @@ Now that you have a better idea of how parsing/rendering works, we can proceed t
 
 The default heading renderers may look like this (you can refer to the Remarkable source code here):
 
-```
+```js
 md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) {
   return '<h' + tokens[idx].hLevel + '>';
 };
@@ -64,13 +64,13 @@ md.renderer.rules.heading_close = function(tokens, idx /*, options, env */) {
 
 That's pretty straightforward: whenever these tokens are found, we render a `<hN>` or `</hN>` HTML tag, where N is the `hLevel` for this heading. That would result in `<h3>Hi there</h3>` being output. But what we want is something closer to this:
 
-```
+```html
 <h3><a class="anchor" id="hi-there"></a>Hi there <a class="hash-link" href="#hi-there">#</a></h3>
 ```
 
 In that case, we need to override our heading rules like so:
 
-```
+```js
 md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) {
   return '<h' + tokens[idx].hLevel + '>' + '<a class="anchor" id="' + toSlug(tokens[idx+1].content) + '"></a>';
 };
@@ -86,7 +86,7 @@ Note that we are referring to `tokens[idx+1]` and `tokens[idx-1]` at various poi
 
 We now need to tell Remarkable to use our extension. We can wrap our rules in a function called `anchors`:
 
-```
+```js
 function anchors(md) {
   md.renderer.rules.heading_open = function(tokens, idx /*, options, env */) {
     return '<h' + tokens[idx].hLevel + '>' + '<a class="anchor" id="' + toSlug(tokens[idx+1].content) + '"></a>';
@@ -100,10 +100,10 @@ function anchors(md) {
 
 We can now tell Remarkable to load this function as a plugin (`md` is our instance of Remarkable):
 
-```
+```js
 this.md.use(anchors);
 ```
 
 ### Future Work
 
-A more advanced extension might add additional parser rules. These rules may add support for new markdown syntax not covered by Remarkable. Say, for example, a custom syntax to embed video when a tag like `@video` is found can be supported by generating a new type of token, that is later used by the renderer to output the necessary `<embed>` HTML tags. This is left as an exercise to the reader for now.
+A more advanced extension might add additional parser rules. These rules may add support for new markdown syntax not covered by Remarkable. Say, for example, a custom syntax to embed video when a tag like `@video` is found can be supported by generating a new type of token, that is later used by the renderer to output the necessary `<embed>` HTML tags. This is left as an exercise to the reader for now.

admin/local-third-party-project-testing.md

@@ -10,7 +10,7 @@ There are two reasonable ways to use a local version of the Docusaurus npm packa
 
 ### Install the package from the Docusaurus repo
 
-```
+```bash
 cd /path/to/testing_project
 mkdir website # if this does not exist already
 cd website
@@ -18,7 +18,7 @@ cd website
 
 If you do not have a `package.json` file in the `website` directory, create one with the following content:
 
-```
+```json
 {
   "scripts": {
     "start": "docusaurus-start",
@@ -31,7 +31,7 @@ If you do not have a `package.json` file in the `website` directory, create one
 
 Then:
 
-```
+```sh
 # Path to your Docusaurus clone
 npm install ../../path/to/docusaurus/
 ```
@@ -46,7 +46,7 @@ Error: Couldn't find preset "react" relative to directory
 
 So, you should install these packages locally. **Base the versions on the versions defined in the Docusaurus `package.json`**. e.g.,
 
-```
+```bash
 # Still in the website directory of the testing project
 npm install babel-plugin-transform-class-properties@^6.24.1
 npm install babel-plugin-transform-object-rest-spread@^6.26.0
@@ -57,7 +57,7 @@ npm install babel-preset-react@^6.24.0
 
 ### Test
 
-```
+```bash
 ./node_modules/.bin/docusaurus-examples # or whatever you want to test, if anything
 ./node_modules/.bin/docusaurus-start
 ```
@@ -68,7 +68,7 @@ Verdaccio is a good local npm server that you can use to test your packages.
 
 ### Install verdaccio
 
-```
+```bash
 npm install --global verdaccio
 ```
 
@@ -78,13 +78,13 @@ When you are ready to test the code that could make up the next version of your
 
 Run verdaccio in a **separate terminal window**:
 
-```
+```bash
 verdaccio
 ```
 
 In another terminal window, get ready to publish your local npm package:
 
-```
+```bash
 # Your clone of Docusaurus
 cd /path/to/docusaurus/
 
@@ -101,7 +101,7 @@ You can navigate to localhost:4873 and you can see that your package was publish
 
 Now install the package in the repo you want to test Docusaurus on.
 
-```
+```bash
 cd /path/to/testing_project/
 mkdir website # if this does not exist already
 cd website
@@ -109,7 +109,7 @@ cd website
 
 If you do not have a `package.json` file in the `website` directory, create one with the following content:
 
-```
+```json
 {
   "scripts": {
     "start": "docusaurus-start",
@@ -122,7 +122,7 @@ If you do not have a `package.json` file in the `website` directory, create one
 
 Then:
 
-```
+```bash
 npm install docusaurus --registry http://localhost:4873 # this may be slower than the normal npm registry
 npm run examples # or whatever you want to test, if anything
 npm run start

admin/publish.md

@@ -18,13 +18,16 @@ If you are not currently logged into npm locally:
 
 The version number should generally increase by some factor than the current one. You can check current version by looking in `package.json`.
 
-```
+```json
-"name": "docusaurus",
+{
-"version": "1.0.0-alpha.41",
+  "name": "docusaurus",
-"repository": {
+  "version": "1.0.0-alpha.41",
-  "type": "git",
+  "repository": {
-  "url": "https://github.com/facebook/Docusaurus.git"
+    "type": "git",
-},
+    "url": "https://github.com/facebook/Docusaurus.git"
+  }
+  ...
+}
 ```
 
 For the above example, you may want to bump the version to `1.0.0-alpha.42` or `1.0.0-beta.1` or `1.0.1`.

admin/testing-changes-on-Docusaurus-itself.md

@@ -6,7 +6,7 @@ If you are developing the Docusaurus core and you want a quick way to test your
 
 It is straightforward to test your Docusaurus changes with Docusaurus.
 
-```
+```bash
 cd /path/to/docusaurus-repo
 npm install
 cd website
@@ -21,7 +21,7 @@ npm run start
 
 Use the following code in VSCode to enable breakpoints. Please ensure you have a later version of node for non-legacy debugging.
 
-```
+```json
 {
   "version": "0.2.0",
   "configurations": [

docs/api-commands.md

@@ -13,13 +13,13 @@ Docusaurus provides a set of scripts to help you generate, serve, and deploy you
 
 The scripts can be run using either Yarn or npm. If you've already gone through our Getting Started guide, you may already be familiar with the `start` command. It's the command that tells Docusaurus to run the `docusaurus-start` script which generates the site and starts up a server, and it's usually invoked like so:
 
-```
+```bash
 yarn run start
 ```
 
 The same script can be invoked using npm:
 
-```
+```bash
 npm run start
 ```
 
@@ -29,13 +29,13 @@ To run a particular script, just replace the `start` command in the examples abo
 
 Some commands support optional arguments. For example, to start a server on port 8080, you can specify the `--port` argument when running `start`:
 
-```
+```bash
 yarn run start --port 8080
 ```
 
 If you run Docusaurus using npm, you can still use the command line arguments by inserting a `--` between `npm run <command>` and the command arguments:
 
-```
+```bash
 npm run start -- --port 8080
 ```
 
@@ -54,6 +54,7 @@ Docusaurus provides some default mappings to allow you to run commands following
 ## Reference
 
 ### `docusaurus-build`
+
 Alias: `build`.
 
 Generates the static website, applying translations if necessary. Useful for building the website prior to deployment.
@@ -63,6 +64,7 @@ See also [`docusaurus-start`](api-commands.md#docusaurus-start-port-number).
 ---
 
 ### `docusaurus-examples [feature]`
+
 Alias: `examples`
 
 When no feature is specified, sets up a minimally configured example website in your project. This command is covered in depth in the [Site Preparation guide](getting-started-preparation.md). Specify a feature `translations` or `versions` to generate the extra example files for that feature.
@@ -70,6 +72,7 @@ When no feature is specified, sets up a minimally configured example website in
 ---
 
 ### `docusaurus-publish`
+
 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:
@@ -100,6 +103,7 @@ You can learn more about configuring automatic deployments with CircleCI in the
 ---
 
 ### `docusaurus-rename-version <currentVersion> <newVersion>`
+
 Alias: `rename-version`
 
 Renames an existing version of the docs to a new version name.
@@ -109,6 +113,7 @@ See the [Versioning guide](guides-versioning.md#renaming-existing-versions) to l
 ---
 
 ### `docusaurus-start [--port <number>]`
+
 Alias: `start`.
 
 This script will build the static website, apply translations if necessary, and then start a local server. The website will be served from port 3000 by default.
@@ -116,6 +121,7 @@ This script will build the static website, apply translations if necessary, and
 ---
 
 ### `docusaurus-version <version>`
+
 Alias: `version`
 
 Generates a new version of the docs. This will result in a new copy of your site being generated and stored in its own versioned folder. Useful for capturing snapshots of API docs that map to specific versions of your software. Accepts any string as a version number.
@@ -125,6 +131,7 @@ See the [Versioning guide](guides-versioning.md) to learn more.
 ---
 
 ### `docusaurus-write-translations`
+
 Alias: `write-translations`
 
 Writes the English for any strings that need to be translated into an `website/i18n/en.json` file. The script will go through every file in `website/pages/en` and through the `siteConfig.js` file and other config files to fetch English strings that will then be translated on Crowdin. See the [Translation guide](guides-translation.md) to learn more.

docs/api-doc-markdown.md

@@ -19,7 +19,7 @@ Documents use the following markdown header fields that are enclosed by a line `
 
 For example:
 
-```markdown
+```yaml
 ---
 id: doc1
 title: My Document
@@ -31,7 +31,7 @@ Versioned documents have their ids altered to include the version number when th
 
 For example:
 
-```markdown
+```yaml
 ---
 id: version-1.0.0-doc1
 title: My Document
@@ -44,7 +44,7 @@ original_id: doc1
 
 For example:
 
-```markdown
+```yaml
 ---
 id: doc-markdown
 title: Markdown Features
@@ -66,7 +66,7 @@ Blog Posts use the following markdown header fields that are enclosed by a line
 
 For example:
 
-```markdown
+```yaml
 ---
 title: My First Blog Post
 author: Frank Li
@@ -85,7 +85,7 @@ You can use relative urls to other documentation files which will automatically
 
 Example:
 
-```markdown
+```md
 [This links to another document](other-document.md)
 ```
 This markdown will automatically get converted into a link to `/docs/other-document.html` (or the appropriately translated/versioned link) once it gets rendered.
@@ -98,11 +98,10 @@ Static assets can be linked to in the same way that documents are, using relativ
 
 Example:
 
-```markdown
+```md
 ![alt-text](assets/doc-image.png)
 ```
 
-
 ### Generating Table of Contents
 
 You can make an autogenerated list of links, which can be useful as a table of contents for API docs.
@@ -111,12 +110,11 @@ In your markdown file, insert a line with the text <`AUTOGENERATED_TABLE_OF_CONT
 
 Example:
 
-```markdown
+```md
 ### `docusaurus.function(a, b)`
 
 Text describing my function
 
-
 ### `docdoc(file)`
 
 Text describing my function
@@ -124,7 +122,7 @@ Text describing my function
 
 will lead to a table of contents of the functions:
 
-```markdown
+```md
 - `docusaurus.function(a, b)`
 - `docdoc(file)`
 ```
@@ -135,7 +133,7 @@ and each function will link to their corresponding sections in the page.
 
 Syntax highlighting is enabled by default on fenced code blocks. The language should be detected automatically, but you can sometimes get better results by specifying the language. You can do so using an [info string](https://github.github.com/gfm/#example-111), following the three opening backticks. The following JavaScript example...
 
-    ```javascript
+    ```js
     ReactDOM.render(
       <h1>Hello, world!</h1>,
       document.getElementById('root')
@@ -144,7 +142,7 @@ Syntax highlighting is enabled by default on fenced code blocks. The language sh
 
 ...would be rendered with syntax highlighting like so:
 
-```javascript
+```js
 ReactDOM.render(
   <h1>Hello, world!</h1>,
   document.getElementById('root')
@@ -153,9 +151,13 @@ ReactDOM.render(
 
 Highlighting is provided by [Highlight.js](https://highlightjs.org) using the theme specified in your `siteConfig.js` file as part of the `highlight` key:
 
-```javascript
+```js
-highlight: {
+{
-  theme: 'default'
+  ...
+  highlight: {
+    theme: 'default'
+  }
+  ...
 }
 ```
 
@@ -165,13 +167,16 @@ You can find the full list of supported themes in the Highlight.js [`styles`](ht
 
 While Highlight.js provides support for [many popular languages out of the box](https://highlightjs.org/static/demo/), you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the `hljs` constant as part of the `highlight` config key. This in turn allows you to call [`registerLanguage`](http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language):
 
-```javascript
+```js
-highlight: {
+{
-  theme: 'default',
+  ...
-  hljs: function(hljs) {
+  highlight: {
-    hljs.registerLanguage('galacticbasic', function(hljs) {
+    theme: 'default',
-      // ...
+    hljs: function(hljs) {
-    });
+      hljs.registerLanguage('galacticbasic', function(hljs) {
+        // ...
+      });
+    }
   }
 }
 ```

docs/api-pages.md

@@ -5,17 +5,17 @@ title: Pages and Styles
 
 Docusaurus provides support for writing pages as React components inside the `website/pages` folder which will share the same header, footer, and styles as the rest of the site.
 
-## Urls for Pages
+## URLs for Pages
 
 Any `.js` files in `website/pages` will be rendered to static html using the path of the file after "pages". Files in `website/pages/en` will also get copied out into `pages` and will OVERRIDE any files of the same name in `pages`. For example, the page for the `website/pages/en/help.js` file will be found at the url `${baseUrl}en/help.js` as well as the url `${baseUrl}help.js`, where `${baseUrl}` is the `baseUrl` field set in your [siteConfig.js file](api-site-config.md).
 
 ## Page Require Paths
 
-Docusaurus provides a few useful React components for users to write their own pages, found in the `CompLibrary` module. This module is provided as part of Docusaurus in `node_modules/docusaurus`, so to access it, pages in the `pages` folder are temporarily copied into `node_modules/docusaurus` when rendering to static html. As seen in the example files, this means that a user page at `pages/en/index.js` uses a require path to `"../../core/CompLibrary.js"` to import the provided components.
+Docusaurus provides a few useful React components for users to write their own pages, found in the `CompLibrary` module. This module is provided as part of Docusaurus in `node_modules/docusaurus`, so to access it, pages in the `pages` folder are temporarily copied into `node_modules/docusaurus` when rendering to static html. As seen in the example files, this means that a user page at `pages/en/index.js` uses a require path to `'../../core/CompLibrary.js'` to import the provided components.
 
-What this means to the user is that if you wish to use the `CompLibrary` module, make sure the require path is set correctly. For example, a page at `page/mypage.js` would use a path `"../core/CompLibrary.js"`.
+What this means to the user is that if you wish to use the `CompLibrary` module, make sure the require path is set correctly. For example, a page at `page/mypage.js` would use a path `'../core/CompLibrary.js'`.
 
-If you wish to use your own components inside the website folder, use `process.cwd()` which will refer to the `website` folder to construct require paths. For example, if you add a component to `website/core/mycomponent.js`, you can use the require path, `"process.cwd() + /core/mycomponent.js"`.
+If you wish to use your own components inside the website folder, use `process.cwd()` which will refer to the `website` folder to construct require paths. For example, if you add a component to `website/core/mycomponent.js`, you can use the require path, `'process.cwd() + /core/mycomponent.js'`.
 
 ## Provided Components
 
@@ -84,7 +84,7 @@ A React component to organize text and images.
 
 **Example**
 
-```
+```jsx
 <GridBlock
   align="center"
   layout="threeColumn"
@@ -145,7 +145,7 @@ Note that this path is valid for files inside `pages/en` and should be adjusted
 
 ## Using Static Assets
 
-Static assets should be placed into the `website/static` folder. They can be accessed by their paths, excluding "static". For example, if the site's `baseUrl` is "/docusaurus/", an image in `website/static/img/logo.png` is available at `/docusaurus/img/logo.png`.
+Static assets should be placed into the `website/static` folder. They can be accessed by their paths, excluding `static`. For example, if the site's `baseUrl` is `/docusaurus/`, an image in `website/static/img/logo.png` is available at `/docusaurus/img/logo.png`.
 
 ## Styles
 

docs/api-site-config.md

@@ -78,11 +78,11 @@ headerLinks: [
 `customDocsPath` - By default, Docusaurus expects your documentation to be in a directory called `docs`. This directory is at the same level as the `website` directory (i.e., not inside the `website` directory). You can specify a custom path to your documentation with this field. **Note that all of your documentation `*.md` files must still reside in a flat hierarchy. You cannot have your documents in nested directories**.
 
 ```js
-customDocsPath: "docs/site"
+customDocsPath: 'docs/site'
 ```
 
 ```js
-customDocsPath: "website-docs"
+customDocsPath: 'website-docs'
 ```
 `disableHeaderTitle` - An option to disable showing the title in the header next to the header icon. Exclude this field to keep the header as normal, otherwise set to `true`.
 
@@ -98,22 +98,22 @@ customDocsPath: "website-docs"
 
 In the below example, we have two sets of font configurations, `myFont` and `myOtherFont`. `Times New Roman` is the preferred font in `myFont`. `-apple-system` is the preferred in `myOtherFont`.
 
-```
+```js
 fonts: {
   myFont: [
-    "Times New Roman",
+    'Times New Roman',
-    "Serif"
+    'Serif'
   ],
   myOtherFont: [
-    "-apple-system",
+    '-apple-system',
-    "system-ui"
+    'system-ui'
   ]
 },
 ```
 
 The above fonts would be represented in your CSS file(s) as variables `$myFont` and `$myOtherFont`.
 
-```
+```css
 h1 {
   font-family: $myFont;
 }
@@ -149,7 +149,7 @@ h1 {
 
 `twitter` - Set this to `true` if you want a Twitter social button to appear at the bottom of your blog posts.
 
-`twitterImage` - Local path to your Twitter card image (e.g., `img/myImage.png`). This image will show up on the Twitter card when your site is shared on Twitter. 
+`twitterImage` - Local path to your Twitter card image (e.g., `img/myImage.png`). This image will show up on the Twitter card when your site is shared on Twitter.
 
 `useEnglishUrl` - If you do not have [translations](guides-translation.md) enabled (e.g., by having a `languages.js` file), but still want a link of the form `/docs/en/doc.html` (with the `en`), set this to `true`.
 
@@ -161,55 +161,55 @@ Users can also add their own custom fields if they wish to provide some data acr
 
 ## Example siteConfig.js with many available fields
 
-```
+```js
 const users = [
   {
-    caption: "User1",
+    caption: 'User1',
-    image: "/test-site/img/docusaurus.svg",
+    image: '/test-site/img/docusaurus.svg',
-    infoLink: "https://www.example.com",
+    infoLink: 'https://www.example.com',
     pinned: true
   }
 ];
 
 const siteConfig = {
-  title: "Docusaurus",
+  title: 'Docusaurus',
-  tagline: "Generate websites!",
+  tagline: 'Generate websites!',
-  url: "https://docusaurus.io",
+  url: 'https://docusaurus.io',
-  baseUrl: "/",
+  baseUrl: '/',
   // For github.io type URLS, you would combine the url and baseUrl like:
-  // url: "https://reasonml.github.io",
+  // url: 'https://reasonml.github.io',
-  // baseUrl: "/reason-react/",
+  // baseUrl: '/reason-react/',
-  organizationName: "facebook",
+  organizationName: 'facebook',
-  projectName: "docusaurus",
+  projectName: 'docusaurus',
   noIndex: false,
   // For no header links in the top nav bar -> headerLinks: [],
   headerLinks: [
-    { doc: "doc1", label: "Docs" },
+    { doc: 'doc1', label: 'Docs' },
-    { page: "help", label: "Help" },
+    { page: 'help', label: 'Help' },
     { search: true },
     { blog: true }
   ],
-  headerIcon: "img/docusaurus.svg",
+  headerIcon: 'img/docusaurus.svg',
-  favicon: "img/favicon.png",
+  favicon: 'img/favicon.png',
   colors: {
-    primaryColor: "#2E8555",
+    primaryColor: '#2E8555',
-    secondaryColor: "#205C3B"
+    secondaryColor: '#205C3B'
   },
-  editUrl: "https://github.com/facebook/docusaurus/edit/master/docs/",
+  editUrl: 'https://github.com/facebook/docusaurus/edit/master/docs/',
   // Users variable set above
   users,
   disableHeaderTitle: true,
   disableTitleTagline: true,
-  separateCss: ["static/css/non-docusaurus", "static/assets/separate-css"],
+  separateCss: ['static/css/non-docusaurus', 'static/assets/separate-css'],
-  footerIcon: "img/docusaurus.svg",
+  footerIcon: 'img/docusaurus.svg',
   translationRecruitingLink:
-    "https://crowdin.com/project/docusaurus",
+    'https://crowdin.com/project/docusaurus',
   algolia: {
     apiKey:
-      "0f9f28b9ab9efae89810921a351753b5",
+      '0f9f28b9ab9efae89810921a351753b5',
-    indexName: "github"
+    indexName: 'github'
   },
-  gaTrackingId: "U-A2352",
+  gaTrackingId: 'UA-12345678-9',
   highlight: {
     theme: 'default'
   },
@@ -220,13 +220,13 @@ const siteConfig = {
       }
     }
   ],
-  scripts: [ "https://docusaurus.io/slash.js" ],
+  scripts: [ 'https://docusaurus.io/slash.js' ],
-  stylesheets: [ "https://docusaurus.io/style.css" ],
+  stylesheets: [ 'https://docusaurus.io/style.css' ],
-  facebookAppId: "1615782811974223",
+  facebookAppId: '1615782811974223',
-  facebookPixelId: "352490515235776",
+  facebookPixelId: '352490515235776',
-  twitter: "true",
+  twitter: 'true',
-  twitterImage: "img/docusaurus.png",
+  twitterImage: 'img/docusaurus.png',
-  ogImage: "img/docusaurus.png",
+  ogImage: 'img/docusaurus.png',
 };
 
 module.exports = siteConfig;

docs/getting-started-installation.md

@@ -3,17 +3,18 @@ id: installation
 title: Installation
 ---
 
-Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure setup for you:
+Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly. To install Docusaurus, we have created an easy script that will get all of the infrastructure set up for you:
 
 1. Ensure you have the latest version of [Node](https://nodejs.org/en/download/) installed. We also recommend you install [Yarn](https://yarnpkg.com/en/docs/install) as well.
 
     > While we recommend Node 8.x or greater, your Node version must at least 6.x.
-    
+
 1. Go into the root of your GitHub repo directory where you will be creating the docs.
 1. `npx docusaurus-init`
+
     > If you don't have Node 8.2+ or if you prefer to install Docusaurus globally, run `yarn global add docusaurus-init` or `npm install --global docusaurus-init`. After that, run `docusaurus-init`.
 
-> After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the `website` directory and typing `yarn outdated docusaurus` or `npm outdated docusaurus`. You can update to the [latest version](https://www.npmjs.com/package/docusaurus) of Docusaurus by typing `yarn upgrade docusaurus --latest` or `npm update docusaurus`.
+After Docusaurus is installed, moving forward, you can check your current version of Docusaurus by going into the `website` directory and typing `yarn outdated docusaurus` or `npm outdated docusaurus`. You can update to the [latest version](https://www.npmjs.com/package/docusaurus) of Docusaurus by typing `yarn upgrade docusaurus --latest` or `npm update docusaurus`.
 
 ## Verifying Installation
 

docs/getting-started-preparation.md

@@ -31,7 +31,7 @@ root-of-repo
 │   └── static
 ```
 
-> You may have already renamed the example blog (website/blog-examples-from-docusaurus and document (docs-examples-from-docusaurus) directories when you [verified the installation](getting-started-installation.md##verifying-installation).
+> You may have already renamed the example blog (`website/blog-examples-from-docusaurus`) and document (`docs-examples-from-docusaurus`) directories when you [verified the installation](getting-started-installation.md##verifying-installation).
 
 - The `website/core/Footer.js` file is a React component that acts as the footer for the site generated by Docusaurus and should be customized by the user.
 - The `website/blog-examples-from-docusaurus` folder contains examples of blog posts written in markdown.
@@ -42,4 +42,4 @@ root-of-repo
 
 You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` files, but may edit them as you wish.
 
-You should keep the `website/pages` and `website/static` folders, but may change the content inside them as you wish. At the bare minimum you should have an `en/index.js` or `en/index.html` file inside `website/pages` and an image to use as your header icon inside `website/static`.
+You should keep the `website/pages` and `website/static` folders, but may change the content inside them as you wish. At the bare minimum you should have an `en/index.js` or `en/index.html` file inside `website/pages` and an image to use as your header icon inside `website/static`.

docs/getting-started-publishing.md

@@ -9,7 +9,7 @@ You should now have a [site up and running locally](getting-started-site-creatio
 
 To create a static build of your website, run the following script from the `website` directory:
 
-```
+```bash
 yarn run build # or `npm run build`
 ```
 
@@ -21,7 +21,7 @@ At this point, you can grab all of the files inside the `website/build` folder a
 
 > For example, both Apache and nginx serve content from `/var/www/html` by default. That said, choosing a web server or provider is outside the scope of Docusaurus.
 
-> When serving the site from your own web server, ensure the web server is serving the asset files with the proper HTTP headers. CSS files should be served with the `content-type` header - `text/css`. In the case of nginx, this would mean setting `include /etc/nginx/mime.types;` in your `nginx.conf` file. See https://github.com/facebook/Docusaurus/issues/602 for more info.
+> When serving the site from your own web server, ensure the web server is serving the asset files with the proper HTTP headers. CSS files should be served with the `content-type` header of `text/css`. In the case of nginx, this would mean setting `include /etc/nginx/mime.types;` in your `nginx.conf` file. See [this issue](https://github.com/facebook/Docusaurus/issues/602) for more info.
 
 ### Hosting on a Service:
 
@@ -97,7 +97,7 @@ If you haven't done so already, you can [setup CircleCI](https://circleci.com/si
 1. Create a `.circleci` folder and create a `config.yml` under that folder.
 1. Copy the text below into `.circleci/config.yml`.
 
-```yml
+```yaml
 # If you only one circle to run on direct commits to master, you can uncomment this out
 # and uncomment the filters: *filter-only-master down below too
 #
@@ -148,7 +148,7 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
 
 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:
 
-```yml
+```yaml
 # Circle CI 2.0 Config File
 # This config file will prevent tests from being run on the gh-pages branch.
 version: 2
@@ -168,13 +168,12 @@ Save this file as `config.yml` and place it in a `.circleci` folder inside your
 Steps to configure your Docusaurus-powered site on Netlify.
 
 1. Select **New site from Git**
-2. Connect to your preferred Git provider.
+1. Connect to your preferred Git provider.
-3. Select the branch to deploy. Default is `master`
+1. Select the branch to deploy. Default is `master`
-4. Configure your build steps:
+1. Configure your build steps:
+    * For your build command enter: `cd website; npm install; npm run build;`
+    * For publish directory: `build/<projectName>` (use the `projectName` from your `siteConfig`)
 
-* For your build command enter: `cd website; npm install; npm run build;`
+1. Click **Deploy site**
-* For publish directory: `build/<projectName>` (use the projectName from your siteConfig)
-
-5. Click **Deploy site**
 
 You can also configure Netlify to rebuild on every commit to your repo, or only `master` branch commits.

docs/getting-started-site-creation.md

@@ -38,13 +38,13 @@ 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.
 
-    ```
+    ```yaml
     ---
     id: intro
     title: Getting Started
     ---
 
-    My *new content* here..
+    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.
@@ -56,10 +56,10 @@ To create a fully functional site, you only need to do a few steps:
 1. Place assets, such as images, in the `website/static/` folder.
 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
+  # Navigate to http://localhost:3000
   ```
 
 ## Special Customization
@@ -74,17 +74,17 @@ If you prefer to have your landing page be straight to your documentation, you c
 ```html
 <!DOCTYPE HTML>
 <html lang="en-US">
-    <head>
+  <head>
-        <meta charset="UTF-8">
+    <meta charset="UTF-8">
-        <meta http-equiv="refresh" content="0; url=docs/id-of-doc-to-land-on.html">
+    <meta http-equiv="refresh" content="0; url=docs/id-of-doc-to-land-on.html">
-        <script type="text/javascript">
+    <script type="text/javascript">
-            window.location.href = "docs/id-of-doc-to-land-on.html"
+      window.location.href = 'docs/id-of-doc-to-land-on.html';
-        </script>
+    </script>
-        <title>Your Site Title Here</title>
+    <title>Your Site Title Here</title>
-    </head>
+  </head>
-    <body>
+  <body>
-        If you are not redirected automatically, follow this <a href='docs/id-of-doc-to-land-on.html'>link</a>.
+    If you are not redirected automatically, follow this <a href="docs/id-of-doc-to-land-on.html">link</a>.
-    </body>
+  </body>
 </html>
 ```
 

docs/guides-blog.md

@@ -9,10 +9,10 @@ To setup your site's blog, start by creating a `blog` folder within your repo's
 
 Then, add a header link to your blog within `siteConfig.js`:
 
-```
+```js
 headerLinks: [
     ...
-    {blog: true, label: 'Blog'},
+    { blog: true, label: 'Blog' },
     ...
 ]
 ```
@@ -23,7 +23,7 @@ To publish in the blog, create a file within the blog folder with a formatted na
 
 For example, at `website/blog/2017-08-18-Introducing-Docusaurus.md`:
 
-```
+```yml
 ---
 author: Frank Li
 authorURL: https://twitter.com/foobarbaz
@@ -48,7 +48,7 @@ The only required field is `title`; however, we provide options to add author in
 
 Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all blog published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
 
-```
+```yaml
 ---
 title: Truncation Example
 ---
@@ -76,7 +76,7 @@ The available options are an integer representing the number of posts you wish t
 
 Example:
 
-```
+```js
 blogSidebarCount: 'ALL'
 ```
 
@@ -99,29 +99,27 @@ You can run your Docusaurus site without a landing page and instead have your bl
 To do this:
 
 1. Create a file `index.html` in `website/static/`.
-
 1. Place the contents of the template below into `website/static/index.html`
-
 1. Customize the `<title>` of `website/static/index.html`
-
 1. Delete the dynamic landing page `website/pages/en/index.js`
 
 > Now, when Docusaurus generates or builds your site, it will copy the file from `static/index.html` and place it in the site's main folder. The static file is served when a visitor arrives on your page. When the page loads it will redirect the visitor to `/blog`.
 
 You can use this template:
 
-```<!DOCTYPE HTML>
+```html
+<!DOCTYPE HTML>
 <html lang="en-US">
-    <head>
+  <head>
-        <meta charset="UTF-8">
+    <meta charset="UTF-8">
-        <meta http-equiv="refresh" content="0; url=blog/">
+    <meta http-equiv="refresh" content="0; url=blog/">
-        <script type="text/javascript">
+    <script type="text/javascript">
-            window.location.href = "blog/"
+      window.location.href = 'blog/';
-        </script>
+    </script>
-        <title>Title of Your Blog</title>
+    <title>Title of Your Blog</title>
-    </head>
+  </head>
-    <body>
+  <body>
-        If you are not redirected automatically, follow this <a href='blog/'>link</a>.
+    If you are not redirected automatically, follow this <a href="blog/">link</a>.
-    </body>
+  </body>
 </html>
 ```

docs/guides-custom-pages.md

@@ -35,13 +35,13 @@ root-of-repo
 
 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).
 
-> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: "about-slash", label: "About/"}`,
+> If you want your page to show up in your navigation header, you will need to update `siteConfig.js` to add to the `headerLinks` element. e.g., `{ page: 'about-slash', label: 'About/' }`,
 
 ## Adding Static Pages
 
 Static `.html` files can also be used, but they will not include Docusaurus' 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`.
+If you wish to use Docusaurus' 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' styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`.
 
 > You can set the [`$wrapPagesHTML` site config option](api-site-config.md#optional-fields) in order to wrap raw HTML fragments with the Docusaurus site styling, header and footer.
 
@@ -58,7 +58,7 @@ Your footer will automatically get applied to all pages on your site, including
 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");
+const React = require('react');
 
 class Footer extends React.Component {
   render() {

docs/guides-navigation.md

@@ -9,11 +9,11 @@ If you want to reference another document in your `docs` folder (or the location
 
 For example, if you are in `doc2.md` and you want to reference `doc1.md`:
 
-```
+```md
 I am referencing a [document](doc1.md).
 ```
 
-> Docusaurus currently does not support documents in nested folders; only in a flatfile structure. We are looking into adding support for nested folders.
+> Docusaurus currently does not support documents in nested folders; only in a flat folder structure. We are looking into adding support for nested folders.
 
 ## How Documents are Linked
 
@@ -23,13 +23,13 @@ For example, creating an empty file such as `docs/getting-started.md` will enabl
 
 Suppose you add this to your document:
 
-```
+```yaml
 ---
 id: intro
 title: Getting Started
 ---
 
-My *new content* here..
+My new content here..
 ```
 
 If you set the `id` field in the markdown header of the file, the doc will then be accessed from a URL of the form `/docs/intro.html`.
@@ -48,37 +48,46 @@ You configure the contents of the sidebar, and the order of its documents, in th
 
 Within `sidebars.json`, add the `id` you used in the document header to existing sidebar/category. In the below case, `docs` is the name of the sidebar and `Getting Started` is a category within the sidebar.
 
-```
+```js
 {
   "docs": {
     "Getting Started": [
       "getting-started"
+    ],
+    ...
+  },
+  ...
+}
 ```
 
 Or you can create a new category within the sidebar:
 
-```
+```js
 {
   "docs": {
-    ...
     "My New Sidebar Category": [
       "getting-started"
     ],
     ...
+  },
+  ...
+}
 ```
 
 ### Adding New Sidebars
 
 You can also put a document in a new sidebar. In the following example, we are creating an `examples-sidebar` sidebar within `sidebars.json` that has a category called `My Example Category` containing a document with an `id` of `my-examples`.
 
-```
+```js
 {
   "examples-sidebar": {
     "My Example Category": [
       "my-examples"
     ],
+    ...
   },
   ...
+}
 ```
 
 It is important to note that until you [add a document from the `"examples-sidebar"` sidebar to the nav bar](#additions-to-the-site-navigation-bar), it will be hidden.
@@ -91,12 +100,15 @@ To expose sidebars, you will add clickable labels to the site navigation bar at
 
 After creating a new sidebar for the site by [adding](#adding-new-sidebars) it to `sidebars.json`, you can expose the new sidebar from the top navigation bar by editing the `headerLinks` field of `siteConfig.js`.
 
-```
+```js
-headerLinks: [
+{
+  headerLinks: [
+    ...
+    { doc: 'my-examples', label: 'Examples' },
+    ...
+  ],
   ...
-  { doc: 'my-examples', label: 'Examples' },
+}
-  ...
-],
 ```
 
 A label called `Examples` will be added to the site navigation bar and when you click on it at the top of your site, the `examples-sidebar` will be shown and the default document will be `my-examples`.
@@ -105,12 +117,15 @@ A label called `Examples` will be added to the site navigation bar and when you
 
 To add custom pages to the site navigation bar, entries can be added to the `headerLinks` of `siteConfig.js`. For example, if we have a page within `website/pages/help.js`, we can link to it by adding the following:
 
-```
+```js
-headerLinks: [
+{
+  headerLinks: [
+    ...
+    { page: 'help', label: 'Help' },
+    ...
+  ],
   ...
-  { page: 'help', label: 'Help' },
+}
-  ...
-],
 ```
 
 A label called `Help` will be added to the site navigation bar and when you click on it at the top of your site, the content from the `help.js` page will be shown.
@@ -119,12 +134,15 @@ A label called `Help` will be added to the site navigation bar and when you clic
 
 Custom links can be added to the site navigation bar with the following entry in `siteConfig.js`:
 
-```
+```js
-headerLinks: [
+{
+  headerLinks: [
+    ...
+    { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
+    ...
+  ],
   ...
-  { href: 'https://github.com/facebook/Docusaurus', label: 'GitHub' },
+}
-  ...
-],
 ```
 
 A label called `GitHub` will be added to the site navigation bar and when you click on it at the top of your site, the content of the external link will be shown.
@@ -139,24 +157,30 @@ You have limited control where the search and languages dropdown elements are sh
 
 If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the `headerLinks` config array:
 
-```
+```js
-headerLinks: [
+{
-  { doc: 'foo', label: 'Foo' },
+  headerLinks: [
-  { search: true },
+    { doc: 'foo', label: 'Foo' },
-  { doc: 'bar', label: 'Bar' },
+    { search: true },
-],
+    { doc: 'bar', label: 'Bar' },
+  ],
+  ...
+}
 ```
 
 ### Languages Dropdown
 
 If translations is enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the `headerLinks` config array:
 
-```
+```js
-headerLinks: [
+{
-  { doc: 'foo', label: 'Foo' },
+  headerLinks: [
-  { languages: true },
+    { doc: 'foo', label: 'Foo' },
-  { doc: 'bar', label: 'Bar' },
+    { languages: true },
-],
+    { doc: 'bar', label: 'Bar' },
+  ],
+  ...
+}
 ```
 
 ## Active Links In Site Navigation Bar
@@ -176,8 +200,11 @@ These are two separate class names so you can have the active styles applied to
 
 We support secondary on-page navigation so you can more easily see the topics associated with a given document. To enable this feature, you need to add the `onPageNav` site configuration [option](api-site-config.md#optional-fields) to your `siteConfig.js`.
 
-```
+```js
-onPageNav: 'separate',
+{
+  onPageNav: 'separate',
+  ...
+}
 ```
 
-Currently, `separate` is the only option available for this field. This provides a separate navigation on the right side of the page.
+Currently, `'separate'` is the only option available for this field. This provides a separate navigation on the right side of the page.

docs/guides-search.md

@@ -13,11 +13,11 @@ Enter your search-only API key and index name into `siteConfig.js` in the `algol
 const siteConfig = {
   ...
   algolia: {
-    apiKey: "my-search-only-api-key-1234",
+    apiKey: 'my-search-only-api-key-1234',
-    indexName: "my-index-name"
+    indexName: 'my-index-name'
   },
   ...
-}
+};
 ```
 
 ## Extra Search Options
@@ -30,11 +30,11 @@ const siteConfig = {
   algolia: {
     ...
     algoliaOptions: {
-      facetFilters: [ "tags:VERSION" ],
+      facetFilters: [ 'tags:VERSION' ],
       hitsPerPage: 5
     }
   },
-}
+};
 ```
 
 ## Controlling the Location of the Search Bar
@@ -54,7 +54,7 @@ const siteConfig = {
     {...}
   ],
   ...
-}
+};
 ```
 
 ## Disabling the Search Bar

docs/guides-translation.md

@@ -9,19 +9,19 @@ Docusaurus allows for easy translation functionality using [Crowdin](https://cro
 
 To generate example files for translations with Docusaurus, run the `examples` script with the command line argument `translations`:
 
-```
+```bash
 npm run examples translations
 ```
 
 or
 
-```
+```bash
 yarn examples translations
 ```
 
 This will create the following files:
 
-```
+```bash
 pages/en/help-with-translations.js
 languages.js
 ../crowdin.yaml
@@ -50,7 +50,7 @@ Wrap strings you want translated in a `<translate>` tag, and add the following `
 
 ```jsx
 ...
-const translate = require("../../server/translate.js").translate;
+const translate = require('../../server/translate.js').translate;
 ...
 <h2>
   <translate>This header will be translated</translate>
@@ -74,12 +74,14 @@ The strings within localized Pages must be extracted and provided to Crowdin.
 
 Add the following script to your `website/package.json` file, if it does not exist already:
 
-```json
+```js
-...
+{
-"scripts": {
+  ...
-  "write-translations": "docusaurus-write-translations"
+  "scripts": {
-},
+    "write-translations": "docusaurus-write-translations"
-...
+  },
+  ...
+}
 ```
 
 Running the script will generate a `website/i18n/en.json` file containing all the strings that will be translated from English into other languages.
@@ -161,7 +163,7 @@ You will want to manually sync your files to and from Crowdin. The sync process
 
 You can add the following to your `package.json` to manually trigger Crowdin.
 
-```json
+```js
 "scripts": {
   "crowdin-upload": "crowdin --config ../crowdin.yaml upload sources --auto-update -b master",
   "crowdin-download": "crowdin --config ../crowdin.yaml download -b master"
@@ -172,7 +174,7 @@ You can add the following to your `package.json` to manually trigger Crowdin.
 
 You will always want to upload your markdown files and translatable strings first and the download the translations section. So run the commands in this order:
 
-```
+```bash
 CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-upload
 CROWDIN_DOCUSAURUS_PROJECT_ID=YOUR_CROWDIN_PROJECT_ID CROWDIN_DOCUSAURUS_API_KEY=YOUR_CROWDIN_API_KEY yarn run crowdin-download
 ```

docs/guides-versioning.md

@@ -19,7 +19,7 @@ You can edit this file later on to customize how you display the versions.
 
 Add the following script to your `package.json` file if it doesn't already exist:
 
-```json
+```js
 ...
 "scripts": {
   "version": "docusaurus-version"
@@ -44,11 +44,11 @@ Running the script again with `yarn run version 2.0.0` will create a version `2.
 This table below summarizes Docusaurus versioning at a glance:
 
 | Version | Tag | URL
-| --- | --- | -- |
+| --- | --- | --- |
 | 1.0.0 | 1.0.0 | docs/1.0.0/doc1.html |
 | 1.0.1 | 1.0.1 | docs/1.0.1/doc1.html |
 | 2.0.0 | current | docs/doc1.html |
-| master branch | next | docs/next/doc1.html |
+| `master` branch | next | docs/next/doc1.html |
 
 ## Versioning Patterns
 
@@ -76,7 +76,7 @@ For example, a document with the original id `doc1` exists for the latest versio
 
 To rename an existing version number to something else, first make sure the following script is in your `package.json` file:
 
-```json
+```js
 ...
 "scripts": {
   "rename-version": "docusaurus-rename-version"

website/blog/2017-12-14-introducing-docusaurus.md

@@ -30,7 +30,7 @@ When Facebook first started their open source program, many teams implemented a
 
 The open source team tried to help mitigate this problem by coming up with a standard template, based on Jekyll, that could be used as a starting point for a project website. We asked our new projects to manually copy our template source to  their repo, write their docs, and publish. This template approach was adopted by most of open source projects launched; some existing projects even converted their custom website implementations to the new template as well.
 
-The problem with the “copy the template to your repo” approach is that, even though the platform is consistent, pushing updates becomes unmaintainable across an entire suite of projects already using the template. This is because we lost control of the template after a project copied it to their repo. Projects were free to modify the template as desired and apply their own project-specific features to it. So while projects share the same site generation platform, they have now diverted enough where they cannot take advantage of the new features we have added to the template over time. There was no easy way we could ask all current projects to “copy” a new version of the template since it might break their existing site or remove features that they have added on their own. Instead, we would have to apply the updates manually to each project one-by-one. This became very problematic when projects started asking for our team for internationalization support within the template, requiring low-level changes to how the template was structured and generated.
+The problem with the "copy the template to your repo" approach is that, even though the platform is consistent, pushing updates becomes unmaintainable across an entire suite of projects already using the template. This is because we lost control of the template after a project copied it to their repo. Projects were free to modify the template as desired and apply their own project-specific features to it. So while projects share the same site generation platform, they have now diverted enough where they cannot take advantage of the new features we have added to the template over time. There was no easy way we could ask all current projects to "copy" a new version of the template since it might break their existing site or remove features that they have added on their own. Instead, we would have to apply the updates manually to each project one-by-one. This became very problematic when projects started asking for our team for internationalization support within the template, requiring low-level changes to how the template was structured and generated.
 
 So we started thinking about what we could do to help mitigate the challenge of keeping sites updated and consistent across our entire portfolio. We also wanted multiple projects to share the same site generation software. We wanted them to start out with the same template, and yet have the flexibility to customize and adapt their site theme to suit their needs. They should be able to extend and customize their site, but when we update the underlying infrastructure with fixes and features, the project should be able update simply and without any breaking changes.
 
@@ -44,9 +44,9 @@ At Facebook, Docusaurus allows us to quickly get different projects up and runni
 
 At its core, we wanted sites running Docusaurus to be simple to use. With one [installation](https://docusaurus.io/docs/en/installation.html) command and some simple [configuration](https://docusaurus.io/docs/en/site-preparation.html), you can actually have a default running website.
 
-When you run docusaurus-init, you will see a structure similar to:
+When you run `docusaurus-init`, you will see a structure similar to:
 
-```
+```bash
 root-of-repo
 ├── docs-examples-from-docusaurus
 │   ├── doc1.md
@@ -68,13 +68,13 @@ root-of-repo
 │   └── static
 ```
 
-With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your [blog posts](https://docusaurus.io/docs/en/blog.html); siteConfig.js is where you make most of the [customizations](https://docusaurus.io/docs/en/site-config.html) for your site; sidebars.json is where you maintain the layout and content of the [sidebar](https://docusaurus.io/docs/en/navigation.html) for your documentation; the pages folder is where you add [custom](https://docusaurus.io/docs/en/custom-pages.html) pages for your site; the static folder is where all of your static assets go (e.g., css stylesheets and images); and the core folder is where you can customize core components of the site, in this case the footer.
+With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your [blog posts](https://docusaurus.io/docs/en/blog.html); `siteConfig.js` is where you make most of the [customizations](https://docusaurus.io/docs/en/site-config.html) for your site; `sidebars.json` is where you maintain the layout and content of the [sidebar](https://docusaurus.io/docs/en/navigation.html) for your documentation; the `pages` folder is where you add [custom](https://docusaurus.io/docs/en/custom-pages.html) pages for your site; the `static` folder is where all of your static assets go (e.g., CSS stylesheets and images); and the `core` folder is where you can customize core components of the site, in this case the footer.
 
 ## How does Docusaurus work?
 
-Docusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing the Jekyll we had in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebookexperimental/Docusaurus/). The general structure looks like:
+Docusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing Jekyll which we used in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebook/Docusaurus/). The general structure looks like:
 
-```
+```bash
 root-of-Docusaurus
 ├── lib
 │   ├── core
@@ -95,7 +95,6 @@ root-of-Docusaurus
 
 The key files here are build-files.js and start-server.js. There are many similarities between these two files: `build-files.js` is used to build the physical artifacts for serving by an external web server. `start-server.js` is used  to run the Docusaurus server and locally test your site. Both go through the following general process to take all of the markdown and configuration to create a runnable website:
 
-
 1. Process your website settings in `siteConfig.js`
 1. Read the document metadata that exists in all the markdown files in your docs directory.
 1. Create a table of contents for your documents based upon the ids extracted from the metadata.
@@ -112,7 +111,7 @@ Note that this process does not take into full account how translations or versi
 
 The final structure of your compiled site will look similar to:
 
-```
+```bash
 build
 ├── website
 │   ├── CNAME

website/versioned_docs/version-1.0.11/guides-custom-pages.md

@@ -42,7 +42,7 @@ Of course, you are also free to write your own pages. It is strongly suggested t
 
 Static `.html` files can also be used, but they will not include Docusaurus' 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`.
+If you wish to use Docusaurus' 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' styles by adding them into the `siteConfig.separateCss` field in `siteConfig.js`.
 
 > You can set the [`$wrapPagesHTML` site config option](api-site-config.md#optional-fields) in order to wrap raw HTML fragments with the Docusaurus site styling, header and footer.