docs(v2): misc updates (#2010)

website/docs/cli.md

@@ -3,7 +3,7 @@ id: cli
 title: CLI
 ---
 
-Docusaurus provides a set of scripts to help you generate, serve, and deploy your website. 
+Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
 
 Once your website is generated, your website package will contain the Docusaurus scripts that you may invoke with your package manager:
 
@@ -43,26 +43,27 @@ Builds and serves the static site with [Webpack Dev Server](https://webpack.js.o
 
 **options**
 
-|Options|Default|Description|
-|-|-|-|
-|`--port`|`3000`|Specifies the port of the dev server|
-|`--host`|`localhost`|Specify a host to use. E.g., if you want your server to be accessible externally, you can use `--host 0.0.0.0`|
-|`--hot-only`|`false`|Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly).|
-|`--no-open`|`false`|Do not open automatically the page in the browser.|
+| Options | Default | Description |
+| --- | --- | --- |
+| `--port` | `3000` | Specifies the port of the dev server |
+| `--host` | `localhost` | Specify a host to use. E.g., if you want your server to be accessible externally, you can use `--host 0.0.0.0` |
+| `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
+| `--no-open` | `false` | Do not open automatically the page in the browser. |
 
 ### `docusaurus build`
 
 Compiles your site for production.
 
 **options**
 
-|Options|Default|Description|
-|-|-|-|
-|`--bundle-analyzer`||Analyze your bundle with [bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer)|
-
+| Options | Default | Description |
+| --- | --- | --- |
+| `--bundle-analyzer` |  | Analyze your bundle with [bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) |
 
 ### `docusaurus swizzle`
 
+> ⚠️ We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.
+
 Swizzle any Docusaurus Theme components with your own component with `docusaurus swizzle`.
 
 ```shell
@@ -79,6 +80,7 @@ Running the above command will copy the relevant theme files to your site folder
 To unswizzle a component, simply delete the files of the swizzled component.
 
 <!-- TODO a separate section for swizzle tutorial -->
+
 To learn more about swizzling, check [here](#).
 
 ### `docusaurus deploy`

website/docs/design-principles.md

@@ -3,7 +3,7 @@ id: design-principles
 title: Design Principles
 ---
 
-_This section is a work in progress._
+> :warning: _This section is a work in progress._
 
 - **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8).
 - **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
@@ -17,8 +17,6 @@ _This section is a work in progress._
 
 We believe that as developers, knowing how a library works is helpful in allowing us to become better at using it. Hence we're dedicating effort into explaining the architecture and various components of Docusaurus with the hope that users reading it will gain a deeper understanding of the tool and be even more proficient in using it.
 
-_This section is a work in progress._
-
 <!--
 
 Explain the principles that guide the development of Docusaurus.

website/docs/introduction.md

@@ -4,7 +4,9 @@ title: Introduction
 description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
 ---
 
-#### :warning: Disclaimers
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+## :warning: Disclaimer
 
 This is an **early and alpha release** of Docusaurus 2. We are making it available early to maximize community participation and feedback. Expect it to evolve a lot over the course of the alpha-beta period. If you are adventurous enough to be an early adopter, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:.
 
@@ -17,11 +19,12 @@ This is an **early and alpha release** of Docusaurus 2. We are making it availab
 **Do not use this if**
 
 - :x: You need a full production-ready solution (<small>try [Docusaurus 1](https://docusaurus.io/) instead</small>)
+- :x: You need the versioning and translation features present in v1
 - :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during alpha period
 
 ## A better Docusaurus is coming to town
 
-<img src="https://docusaurus.io/img/slash-introducing.svg" alt="Docusaurus"/>
+<img alt="Docusaurus " src={useBaseUrl('img/slash-introducing.svg')} />
 
 Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs (_coming soon_), and i18n (_coming soon_).
 

website/docs/lifecycle-apis.md

@@ -3,7 +3,7 @@ id: lifecycle-apis
 title: Lifecycle APIs
 ---
 
-_This section is a work in progress._
+> :warning: _This section is a work in progress._
 
 Lifecycle APIs are shared by Themes and Plugins.
 

website/docs/styling-layout.md

@@ -119,4 +119,4 @@ The class names which will be processed by webpack into a globally unique class
 
 ### CSS-in-JS
 
-_This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640)._
+> :warning: _This section is a work in progress._ [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).\_

website/docs/theme-classic.md

@@ -3,7 +3,7 @@ id: theme-classic
 title: Classic Theme Configuration
 ---
 
-_This section is a work in progress._
+> :warning: _This section is a work in progress._
 
 ## Common
 
@@ -71,8 +71,8 @@ module.exports = {
     prism: {
       theme: require('prism-react-renderer/themes/dracula'),
     },
-  }
-}
+  },
+};
 ```
 
 ### Default language
@@ -86,6 +86,6 @@ module.exports = {
     prism: {
       defaultLanguage: 'javascript',
     },
-  }
-}
+  },
+};
 ```