From 9e8d6d2148706bcb9914bf613507bfdafeaad2c8 Mon Sep 17 00:00:00 2001
From: Eric Vicenti <evv@fb.com>
Date: Tue, 8 Aug 2017 11:09:03 -0700
Subject: [PATCH] Add navigation guide

---
 docs/guides-navigation.md | 115 ++++++++++++++++++++++++++++++++++++++
 website/sidebar.json      |   1 +
 2 files changed, 116 insertions(+)
 create mode 100644 docs/guides-navigation.md

diff --git a/docs/guides-navigation.md b/docs/guides-navigation.md
new file mode 100644
index 0000000000..cff907eca4
--- /dev/null
+++ b/docs/guides-navigation.md
@@ -0,0 +1,115 @@
+---
+id: navigation
+title: Navigation and Sidebars
+---
+
+## New Hidden Docs
+
+New markdown files within `docs` will show up as pages on the website. Creating a file such as "docs/getting-started.md" will enable the new page `/docs/getting-started.html`.
+
+To change the id (link name) of the file, set the `id` field in the markdown header. At the top of `getting-started.md`:
+
+```
+---
+id: intro
+title: Getting Started
+---
+
+My *new content* here..
+```
+
+Now, the doc can be accessed from `/docs/intro.html`.
+
+
+## Adding Docs to a Sidebar
+
+Now we want our new page to show up on the sidebar. We configure the order of the sidebar in `website/sidebars.json`.
+
+Within `sidebars.json`, add the doc ID within an existing sidebar/category:
+
+```
+{
+  "docs": {
+    "Getting Started": [
+      "getting-started"
+```
+
+Or you can create a new category within the sidebar:
+
+```
+{
+  "docs": {
+    ...
+    "My New Sidebar Category": [
+      "getting-started"
+    ],
+    ...
+```
+
+## New Hidden Sections
+
+You can also put the doc in a new sidebar. In this case we are creating a `intro` section within `sidebars.json`.
+
+```
+{
+  "intro": {
+    "My Sidebar Category": [
+      "getting-started"
+    ],
+  },
+  ...
+```
+
+Keep in mind, until you add the section to the nav bar (below), this new "intro" section of the site will be hidden with no links going to it.
+
+
+
+## Adding doc to site nav bar
+
+After creating a new section of the site by adding to `sidebars.json`, you can link to the new doc from the top navigation bar by editing the `headerLinks` field of `siteConfig.js`.
+
+```
+headerLinks: [
+  ...
+  {doc: 'intro', label: 'Getting Started'},
+  ...
+],
+```
+
+## Custom page links in nav bar
+
+To add custom pages to the 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:
+
+```
+headerLinks: [
+  ...
+  {page: 'help', label: 'Help'},
+  ...
+],
+```
+
+## External links in nav bar
+
+Custom links can be added to the nav bar with the following entry in `siteConfig.js`:
+
+```
+headerLinks: [
+  ...
+  {href: 'https://github.com/facebookexperimental/Docusaurus', label: 'GitHub'},
+  ...
+],
+```
+
+To open external links in a new tab, provide an `external: true` flag within the header link config.
+
+## Search bar position in nav bar
+
+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:
+
+```
+headerLinks: [
+  {doc: 'foo', label: 'Foo'},
+  {search: true},
+  {doc: 'bar', label: 'Bar'},
+],
+```
\ No newline at end of file
diff --git a/website/sidebar.json b/website/sidebar.json
index 98ec6db72d..0cdcc2ef9d 100644
--- a/website/sidebar.json
+++ b/website/sidebar.json
@@ -4,6 +4,7 @@
       "getting-started"
     ],
     "Guides": [
+      "navigation",
       "translation",
       "search"
     ],