v1.9.0 (#1417)

* v1.9.0

* misc: add links to PR

CHANGELOG.md

@@ -6,6 +6,36 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+## [1.9.0] - 2019-4-29
+
+In preparation of F8 where @yangshun will be holding a classroom session on building a Docusaurus site, we've added a tutorial to teach people how to create a versioned Docusaurus site.
+
+We also revamped the `docusaurus-init` script such that the theme colors are random and you partnered with [unDraw](https://undraw.co/) to generate illustrations that match your theme color! Check it out!
+
+The sidebar icon on mobile screens have been changed to a more conventional hamburger style icon which is more intuitibe. If you customized that part, check if your site's layout broke because of it.
+
+Lastly, welcome Pulsar, Mockit and React Testing Library as users!
+
+Thank you to the following contributors:
+
+- @endiliey
+- @yangshun
+- @Alan-Cha
+- @ntucker
+- @wilsonmar
+- @NishealJ
+- @Hongarc
+
+### Fixed/Added
+
+- docs: consistent badge style ([#1371](https://github.com/facebook/Docusaurus/pull/1371))
+- fix: prism syntax highlight .tsx properly ([#1391](https://github.com/facebook/Docusaurus/pull/1391))
+- feat: add tutorial ([#1381](https://github.com/facebook/Docusaurus/pull/1381))
+- feat: change icon for navToggle ([#1394](https://github.com/facebook/Docusaurus/pull/1394))
+- fix: blog docs example as object property ([#1403](https://github.com/facebook/Docusaurus/pull/1403))
+- docs: docs-examples-from-docusaurus is now installed as doc ([#1406](https://github.com/facebook/Docusaurus/pull/1406))
+- fix: upgrade underscore.string to 3.3.5 ([#1404](https://github.com/facebook/Docusaurus/pull/1404))
+
 ## [1.8.1] - 2019-4-15
 
 We accidentally published 2.0.0-alpha.5 as latest on npm. Please do not use that and instead use the 1.x version.

packages/docusaurus-1.x/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "2.0.0-alpha.11",
+  "version": "1.9.0",
   "license": "MIT",
   "keywords": [
     "documentation",

packages/docusaurus-init-1.x/package.json

@@ -1,7 +1,7 @@
 {
   "name": "docusaurus-init",
   "description": "Initialization script for Docusaurus",
-  "version": "2.0.0-alpha.11",
+  "version": "1.9.0",
   "license": "MIT",
   "preferGlobal": true,
   "keywords": [

website-1.x/versioned_docs/version-1.9.0/getting-started-installation.md

@@ -0,0 +1,120 @@
+---
+id: version-1.9.0-installation
+title: Installation
+original_id: installation
+---
+
+Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
+
+## Installing 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.
+
+    > You have to be on Node >= 8.x and Yarn >= 1.5.
+
+1.  Create a project, if none exists, and change your directory to this project's root.
+
+    You will be creating the docs in this directory. The root directory may
+    contain other files. The Docusaurus installation script will create two new
+    directories: `docs` and `website`.
+
+    > Commonly, either an existing or newly created GitHub project will be the location for your Docusaurus site, but that is not mandatory to use Docusaurus.
+
+1.  Run the Docusaurus installation script: `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`.
+
+## Verifying Installation
+
+Along with previously existing files and directories, your root directory will now contain a structure similar to:
+
+```bash
+root-directory
+├── Dockerfile
+├── README.md
+├── docker-compose.yml
+├── docs
+│   ├── doc1.md
+│   ├── doc2.md
+│   ├── doc3.md
+│   ├── exampledoc4.md
+│   └── exampledoc5.md
+└── website
+    ├── blog
+    │   ├── 2016-03-11-blog-post.md
+    │   ├── 2017-04-10-blog-post-two.md
+    │   ├── 2017-09-25-testing-rss.md
+    │   ├── 2017-09-26-adding-rss.md
+    │   └── 2017-10-24-new-version-1.0.0.md
+    ├── core
+    │   └── Footer.js
+    ├── package.json
+    ├── pages
+    ├── sidebars.json
+    ├── siteConfig.js
+    └── static
+```
+
+## Running the example website
+
+After running the Docusaurus initialization script, `docusaurus-init` as
+described in the [Installation](#installing-docusaurus) section, you will have a
+runnable, example website to use as your site's base. To run:
+
+1.  `cd website`
+1.  From within the `website` directory, run the local webserver using
+    `yarn start` or `npm start`.
+1.  Load the example site at http://localhost:3000 if it did not already open
+    automatically. If port 3000 has already been taken, another port will be used. Look at the console messages to see which.
+
+    You should see the example site loaded in your web browser. There's also a LiveReload server running and any changes made to the docs and files in the `website` directory will cause the page to refresh. A randomly generated primary and secondary theme color will be picked for you.
+
+![](/img/getting-started-preparation-verify.png)
+
+### Launching the server behind a proxy
+
+If you are behind a corporate proxy, you need to disable it for the development server requests. It can be done using the `NO_PROXY` environment variable.
+
+```sh
+SET NO_PROXY=localhost
+yarn start (or npm run start)
+```
+
+## Updating Your Docusaurus Version
+
+At any time after Docusaurus is installed, you can check your current version of Docusaurus by going into the `website` directory and typing `yarn outdated docusaurus` or `npm outdated docusaurus`.
+
+You will see something like this:
+
+```
+$ yarn outdated
+Using globally installed version of Yarn
+yarn outdated v1.5.1
+warning package.json: No license field
+warning No license field
+info Color legend :
+ "<red>"    : Major Update backward-incompatible updates
+ "<yellow>" : Minor Update backward-compatible features
+ "<green>"  : Patch Update backward-compatible bug fixes
+Package    Current Wanted Latest Package Type    URL
+docusaurus 1.0.9   1.2.0  1.2.0  devDependencies https://github.com/facebook/Docusaurus#readme
+✨  Done in 0.41s.
+```
+
+> If there is no noticeable version output from the `outdated` commands, then you are up-to-date.
+
+You can update to the [latest version](https://www.npmjs.com/package/docusaurus) of Docusaurus by:
+
+```
+yarn upgrade docusaurus --latest
+```
+
+or
+
+```
+npm update docusaurus
+```
+
+> If you are finding that you are getting errors after your upgrade, try to either clear your Babel cache (usually it's in a [temporary directory](https://babeljs.io/docs/en/babel-register/#environment-variables) or run the Docusaurus server (e.g., `yarn start`) with the `BABEL_DISABLE_CACHE=1` environment configuration.

website-1.x/versioned_docs/version-1.9.0/getting-started-preparation.md

@@ -0,0 +1,58 @@
+---
+id: version-1.9.0-site-preparation
+title: Site Preparation
+original_id: site-preparation
+---
+
+After [installing Docusaurus](getting-started-installation.md), you now have a skeleton to work from for your specific website. The following discusses the rest of the Docusaurus structure in order for you to prepare your site.
+
+## Directory Structure
+
+As shown after you [installed Docusaurus](getting-started-installation.md), the initialization script created a directory structure similar to:
+
+```bash
+root-directory
+├── docs
+│   ├── doc1.md
+│   ├── doc2.md
+│   ├── doc3.md
+│   ├── exampledoc4.md
+│   └── exampledoc5.md
+└── website
+    ├── blog
+    │   ├── 2016-03-11-blog-post.md
+    │   ├── 2017-04-10-blog-post-two.md
+    │   ├── 2017-09-25-testing-rss.md
+    │   ├── 2017-09-26-adding-rss.md
+    │   └── 2017-10-24-new-version-1.0.0.md
+    ├── core
+    │   └── Footer.js
+    ├── package.json
+    ├── pages
+    ├── sidebars.json
+    ├── siteConfig.js
+    └── static
+```
+
+### Directory Descriptions
+
+* **Documentation Source Files**: The `docs` directory
+  contains example documentation files written in Markdown.
+* **Blog**: The `website/blog` directory contains examples of blog posts written in markdown.
+* **Pages**: The `website/pages` directory contains example top-level pages for the site.
+* **Static files and images**: The `website/static` directory contains static assets used by the example site.
+
+### Key Files
+
+* **Footer**: 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.
+* **Configuration file**: The `website/siteConfig.js` file is the main
+  configuration file used by Docusaurus.
+* **Sidebars**: The `sidebars.json` file contains the structure and ordering
+  of the documentation files.
+
+## Preparation Notes
+
+You will need to keep the `website/siteConfig.js` and `website/core/Footer.js` files, but may edit them as you wish. The value of the `customDocsPath` key in `website/siteConfig.js` can be modified if you wish to use a different directory name or path. The `website` directory can also be renamed to anything you want it to be.
+
+However, you should keep the `website/pages` and `website/static` directories. You 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`.

website-1.x/versioned_docs/version-1.9.0/guides-blog.md

@@ -0,0 +1,138 @@
+---
+id: version-1.9.0-adding-blog
+title: Adding a Blog
+original_id: adding-blog
+---
+
+## Initial Setup
+
+To setup your site's blog, start by creating a `blog` directory within your repo's `website` directory.
+
+Then, add a header link to your blog within `siteConfig.js`:
+
+```js
+headerLinks: [
+    ...
+    { blog: true, label: 'Blog' },
+    ...
+]
+```
+
+## Adding Posts
+
+To publish in the blog, create a file within the blog directory with a formatted name of `YYYY-MM-DD-My-Blog-Post-Title.md`. The post date is extracted from the file name.
+
+For example, at `website/blog/2017-08-18-Introducing-Docusaurus.md`:
+
+```yml
+---
+author: Frank Li
+authorURL: https://twitter.com/foobarbaz
+authorFBID: 503283835
+title: Introducing Docusaurus
+---
+
+Lorem Ipsum...
+```
+
+## Header Options
+
+The only required field is `title`; however, we provide options to add author information to your blog post as well.
+
+* `author` - The text label of the author byline.
+* `authorURL` - The URL associated with the author. This could be a Twitter, GitHub, Facebook account, etc.
+* `authorFBID` - The Facebook profile ID that is used to fetch the profile picture.
+* `authorImageURL` - The URL to the author's image. (Note: If you use both `authorFBID` and `authorImageURL`, `authorFBID` will take precedence. Don't include `authorFBID` if you want `authorImageURL` to appear.)
+* `title` - The blog post title.
+
+## Summary Truncation
+
+Use the `<!--truncate-->` marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above `<!--truncate-->` will be part of the summary. For example:
+
+```yaml
+---
+title: Truncation Example
+---
+
+All this will be part of the blog post summary.
+
+Even this.
+
+<!--truncate-->
+
+But anything from here on down will not be.
+
+Not this.
+
+Or this.
+```
+
+## Changing How Many Blog Posts Show on Sidebar
+
+By default, 5 recent blog posts are shown on the sidebar.
+
+You can configure a specific amount of blog posts to show by adding a `blogSidebarCount` setting to your `siteConfig.js`.
+
+The available options are an integer representing the number of posts you wish to show or a string with the value `'ALL'`.
+
+Example:
+
+```js
+blogSidebarCount: 'ALL',
+```
+
+## Changing The Sidebar Title
+
+You can configure a specific sidebar title by adding a `blogSidebarTitle` setting to your `siteConfig.js`.
+
+The option is an object which can have the keys `default` and `all`. Specifying a value for `default` allows you to change the default sidebar title. Specifying a value for `all` allows you to change the sidebar title when the `blogSidebarCount` option is set to `'ALL'`.
+
+Example:
+
+```js
+blogSidebarTitle: { default: 'Recent posts', all: 'All blog posts' },
+```
+
+## RSS Feed
+
+Docusaurus provides a simple RSS feed for your blog posts. Both RSS and Atom feed formats are supported. This data is automatically to your website page's HTML `<HEAD>` tag.
+
+A summary of the post's text is provided in the RSS feed up to the `<!--truncate-->`. If no `<!--truncate-->` tag is found, then all text up 250 characters are used.
+
+## Social Buttons
+
+If you want Facebook and/or Twitter social buttons at the bottom of your blog posts, set the `facebookAppId` and/or `twitter` [site configuration](api-site-config.md) options in `siteConfig.js`.
+
+## Advanced Topics
+
+### I want to run in "Blog Only" mode.
+
+You can run your Docusaurus site without a landing page and instead have your blog load first.
+
+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 directory. 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:
+
+```html
+<!DOCTYPE HTML>
+<html lang="en-US">
+  <head>
+    <meta charset="UTF-8">
+    <meta http-equiv="refresh" content="0; url=blog/">
+    <script type="text/javascript">
+      window.location.href = 'blog/';
+    </script>
+    <title>Title of Your Blog</title>
+  </head>
+  <body>
+    If you are not redirected automatically, follow this <a href="blog/">link</a>.
+  </body>
+</html>
+```