Merge branch 'master' into 1114-2

CHANGELOG.md

@@ -6,6 +6,48 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) a
 
 ## [Unreleased]
 
+## [1.6.0] - 2018-12-1
+
+This releases includes few bug fixes and features. One notable feature allows user to change/remove `docs` prefix from the generated docusaurus URL.
+
+Welcome to our newest users, [React-Slate](http://react-slate.surge.sh/), [Hemera](https://hemerajs.github.io/hemera/), [React-Redux](https://react-redux.js.org/), [Spectrum](https://libspectrum.io/), [TorchCraftAI](https://torchcraft.github.io/TorchCraftAI/), and [Haul](https://callstack.github.io/haul/).
+
+Thank you to the following contributors who helped with this release:
+
+- @yangshun
+- @endiliey
+- @JoelMarcey
+- @andrewShillito
+- @kahkhang
+- @domcorvasce
+- @ellereeeee
+- @maxaggedon
+- @gianlucadonato
+- @tsmrachel 
+- @Shriram-Balaji
+- @noraj
+- @alexperez
+- @wgao19
+
+### Fixed/Changed
+
+- Live reload not working on second try ([#1103](https://github.com/facebook/Docusaurus/pull/1103))
+- Fix missing TOC on i18n pages ([#1119](https://github.com/facebook/Docusaurus/pull/1119))
+- Fix docusaurus-version not working for subcategory in sidebar ([#1124](https://github.com/facebook/Docusaurus/pull/1124))
+- Fix docusaurus-version to allow duplicate id in different subdirectory ([#1125](https://github.com/facebook/Docusaurus/pull/1125))
+
+##  Docs
+- Add guide on setting custom docs path ([#1098](https://github.com/facebook/Docusaurus/pull/1098))
+- Document that `website` folder can be renamed ([#1106](https://github.com/facebook/Docusaurus/pull/1106))
+- Specify markdown flavor ([#1118](https://github.com/facebook/Docusaurus/pull/1118))
+
+### Added
+
+- Allow modifying/removing `docs` route in generated url ([#914](https://github.com/facebook/Docusaurus/pull/914))
+- Use `sidebar_label` in addition to `title` for prev/next button ([#1122](https://github.com/facebook/Docusaurus/pull/1122))
+- Warn the users if any unresolved markdown links ([#1116](https://github.com/facebook/Docusaurus/pull/1116))
+- Customizable search placeholder ([#1126](https://github.com/facebook/Docusaurus/pull/1126))
+
 ## [1.5.1] - 2018-11-03
 
 A release where we had many external contributors! Very excited to see the community being involved in the project.
@@ -836,7 +878,9 @@ N/A
   - Blog
   - Documentation
 
-[unreleased]: https://github.com/facebook/Docusaurus/compare/v1.5.0...HEAD
+[unreleased]: https://github.com/facebook/Docusaurus/compare/v1.6.0...HEAD
+[1.6.0]: https://github.com/facebook/Docusaurus/compare/v1.5.1...v1.6.0
+[1.5.1]: https://github.com/facebook/Docusaurus/compare/v1.4.0...v1.5.1
 [1.5.0]: https://github.com/facebook/Docusaurus/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/facebook/Docusaurus/compare/v1.3.3...v1.4.0
 [1.3.3]: https://github.com/facebook/Docusaurus/compare/v1.3.2...v1.3.3

docs/api-doc-markdown.md

@@ -17,7 +17,7 @@ Documents use the following markdown header fields that are enclosed by a line `
 
 `hide_title`: Whether to hide the title at the top of the doc.
 
-`sidebar_label`: The text shown in the document sidebar for this document. If this field is not present, the document's `sidebar_label` will default to its `title`.
+`sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's `sidebar_label` will default to its `title`.
 
 For example:
 

docs/api-pages.md

@@ -5,6 +5,25 @@ title: Pages and Styles
 
 Docusaurus provides support for writing pages as React components inside the `website/pages` directory which will share the same header, footer, and styles as the rest of the site.
 
+## Provided Props
+
+Docusaurus provides your [siteConfig.js](api-site-config.md) as a `config` props. Hence, you can access `baseUrl` or `title` through this props.
+
+Example
+
+```js
+const React = require('react');
+
+class MyPage extends React.Component {
+  render() {
+    const siteConfig = this.props.config;
+    return <div>{siteConfig.title}</div>;
+  }
+}
+
+module.exports = MyPage;
+```
+
 ## 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).
@@ -31,7 +50,7 @@ module.exports = MyPage;
 
 ## Description for Pages
 
-By default, the description your page is `tagline` set in [`siteConfig.js`](api-site-config.md). If you want to set a specific description for your custom pages, add a `description` class property on your exported React component. 
+By default, the description your page is `tagline` set in [`siteConfig.js`](api-site-config.md). If you want to set a specific description for your custom pages, add a `description` class property on your exported React component.
 
 Example:
 
@@ -138,7 +157,7 @@ A React component to organize text and images.
   className="myCustomClass"
   contents={[
     {
-      title: `[Learn](${siteConfig.baseUrl}docs/tutorial.html)`,
+      title: `[Learn](${siteConfig.baseUrl}${siteConfig.docsUrl}/tutorial.html)`,
       content: 'Learn how to use this project',
       image: siteConfig.baseUrl + 'img/learn.png',
       imageAlt: 'Learn how to use this project',

docs/api-site-config.md

@@ -64,10 +64,6 @@ headerLinks: [
 ],
 ```
 
-#### `noIndex` [boolean]
-
-Boolean. If true, Docusaurus will politely ask crawlers and search engines to avoid indexing your site. This is done with a header tag and so only applies to docs and pages. Will not attempt to hide static resources. This is a best effort request. Malicious crawlers can and will still index your site.
-
 #### `organizationName` [string]
 
 GitHub username of the organization or user hosting this project. This is used by the publishing script to determine where your GitHub pages website will be hosted.
@@ -130,6 +126,11 @@ customDocsPath: 'website-docs';
 
 The default version for the site to be shown. If this is not set, the latest version will be shown.
 
+#### `docsUrl` [string]
+
+The base url for all docs file. Set this field to `''` to remove the `docs` prefix of the documentation URL. 
+If unset, it is defaulted to `docs`.
+
 #### `disableHeaderTitle` [boolean]
 
 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`.
@@ -246,6 +247,10 @@ Path to your web app manifest (e.g., `manifest.json`). This will add a `<link>`
 
 An array of plugins to be loaded by Remarkable, the markdown parser and renderer used by Docusaurus. The plugin will receive a reference to the Remarkable instance, allowing custom parsing and rendering rules to be defined.
 
+#### `noIndex` [boolean]
+
+Boolean. If true, Docusaurus will politely ask crawlers and search engines to avoid indexing your site. This is done with a header tag and so only applies to docs and pages. Will not attempt to hide static resources. This is a best effort request. Malicious crawlers can and will still index your site.
+
 #### `ogImage` [string]
 
 Local path to an Open Graph image (e.g., `img/myImage.png`). This image will show up when your site is shared on Facebook and other websites/apps where the Open Graph protocol is supported.

docs/getting-started-publishing.md

@@ -162,8 +162,17 @@ Now, whenever a new commit lands in `master`, CircleCI will run your suite of te
 
 ### 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:
+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 (This can also result in chat/slack build failure notifications).
 
+You can work around this easily by:
+- Setting the environment variable `CUSTOM_COMMIT_MESSAGE` flag to the `publish-gh-pages` command with the contents of `[skip ci]`.
+e.g. 
+```bash
+CUSTOM_COMMIT_MESSAGE="[skip ci]" \
+  yarn run publish-gh-pages # or `npm run publish-gh-pages`
+```
+
+- Alternatively you can work around this by creating a basic Circle CI config with the following contents:
 ```yaml
 # Circle CI 2.0 Config File
 # This config file will prevent tests from being run on the gh-pages branch.

docs/guides-search.md

@@ -61,6 +61,20 @@ const siteConfig = {
 };
 ```
 
+## Customizing the placeholder
+
+If you want to change the placeholder (which defaults to *Search*), add the `placeholder` field in your config. For example, you may want the search bar to display *Ask me something*:
+
+```js
+const siteConfig = {	
+  ...	
+  algolia: {	
+    ...	
+    placeholder: 'Ask me something'
+  },	
+};	
+```
+
 ## Disabling the Search Bar
 
 To disable the search bar, comment out (recommended) or delete the `algolia` section in the `siteConfig.js` file.

docs/guides-translation.md

@@ -65,7 +65,7 @@ You can also include an optional description attribute to give more context to a
 <p>
 ```
 
-> The `<translate>` tag generally works well on pure strings. If you have a string like "Docusaurus currently provides support to help your website use [translations](${siteConfig.baseUrl}docs/${this.props.language}/translation.html)", wrapping the `<translation>` tag around that entire string will cause issues because of the markdown linking, etc. Your options are to not translate those strings, or spread a bunch of `<translate>` tags amongst the pure substrings of that string.
+> The `<translate>` tag generally works well on pure strings. If you have a string like "Docusaurus currently provides support to help your website use [translations](${siteConfig.baseUrl}${siteConfig.docsUrl}/${this.props.language}/translation.html)", wrapping the `<translation>` tag around that entire string will cause issues because of the markdown linking, etc. Your options are to not translate those strings, or spread a bunch of `<translate>` tags amongst the pure substrings of that string.
 
 ## Gathering Strings to Translate
 

v1/examples/basics/core/Footer.js

@@ -10,7 +10,10 @@ const React = require('react');
 class Footer extends React.Component {
   docUrl(doc, language) {
     const baseUrl = this.props.config.baseUrl;
-    return `${baseUrl}docs/${language ? `${language}/` : ''}${doc}`;
+    const docsUrl = this.props.config.docsUrl;
+    const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`;
+    const langPart = `${language ? `${language}/` : ''}`;
+    return `${baseUrl}${docsPart}${langPart}${doc}`;
   }
 
   pageUrl(doc, language) {

v1/examples/basics/pages/en/help.js

@@ -12,47 +12,43 @@ const CompLibrary = require('../../core/CompLibrary.js');
 const Container = CompLibrary.Container;
 const GridBlock = CompLibrary.GridBlock;
 
-const siteConfig = require(`${process.cwd()}/siteConfig.js`);
-
-function docUrl(doc, language) {
-  return `${siteConfig.baseUrl}docs/${language ? `${language}/` : ''}${doc}`;
-}
-
-class Help extends React.Component {
-  render() {
-    const language = this.props.language || '';
-    const supportLinks = [
-      {
-        content: `Learn more using the [documentation on this site.](${docUrl(
-          'doc1.html',
-          language,
-        )})`,
-        title: 'Browse Docs',
-      },
-      {
-        content: 'Ask questions about the documentation and project',
-        title: 'Join the community',
-      },
-      {
-        content: "Find out what's new with this project",
-        title: 'Stay up to date',
-      },
-    ];
-
-    return (
-      <div className="docMainWrapper wrapper">
-        <Container className="mainContainer documentContainer postContainer">
-          <div className="post">
-            <header className="postHeader">
-              <h1>Need help?</h1>
-            </header>
-            <p>This project is maintained by a dedicated group of people.</p>
-            <GridBlock contents={supportLinks} layout="threeColumn" />
-          </div>
-        </Container>
-      </div>
-    );
-  }
+function Help(props) {
+  const {config: siteConfig, language = ''} = props;
+  const {baseUrl, docsUrl} = siteConfig;
+  const docsPart = `${docsUrl ? `${docsUrl}/` : ''}`;
+  const langPart = `${language ? `${language}/` : ''}`;
+  const docUrl = doc => `${baseUrl}${docsPart}${langPart}${doc}`;
+
+  const supportLinks = [
+    {
+      content: `Learn more using the [documentation on this site.](${docUrl(
+        'doc1.html',
+      )})`,
+      title: 'Browse Docs',
+    },
+    {
+      content: 'Ask questions about the documentation and project',
+      title: 'Join the community',
+    },
+    {
+      content: "Find out what's new with this project",
+      title: 'Stay up to date',
+    },
+  ];
+
+  return (
+    <div className="docMainWrapper wrapper">
+      <Container className="mainContainer documentContainer postContainer">
+        <div className="post">
+          <header className="postHeader">
+            <h1>Need help?</h1>
+          </header>
+          <p>This project is maintained by a dedicated group of people.</p>
+          <GridBlock contents={supportLinks} layout="threeColumn" />
+        </div>
+      </Container>
+    </div>
+  );
 }
 
 module.exports = Help;