Proposal for new doc menu structure (#1405)

* website: New doc menu layout

* Merge sources

* Operate HR via menu_prefix too

* Fix categories in /examples

website/src/docs/aws-s3-multipart.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 53
+order: 3
 title: "AWS S3 Multipart"
 module: "@uppy/aws-s3-multipart"
 permalink: docs/aws-s3-multipart/
+category: 'Destinations'
 ---
 
 The `@uppy/aws-s3-multipart` plugin can be used to upload files directly to an S3 bucket using S3's Multipart upload strategy. With this strategy, files are chopped up in parts of 5MB+ each, so they can be uploaded concurrently. It is also very reliable: if a single part fails to upload, only that 5MB chunk has to be retried.

website/src/docs/aws-s3.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 52
+order: 2
 title: "AWS S3"
 module: "@uppy/aws-s3"
 permalink: docs/aws-s3/
+category: 'Destinations'
 ---
 
 The `@uppy/aws-s3` plugin can be used to upload files directly to an S3 bucket.

website/src/docs/companion.md

@@ -5,6 +5,7 @@ title: "Companion"
 module: "@uppy/companion"
 permalink: docs/companion/
 alias: docs/server/
+category: 'Docs'
 ---
 
 > Companion was previously known as Uppy Server. It was renamed in v0.14.0.

website/src/docs/contributing.md

@@ -2,6 +2,7 @@
 title: "Contributing"
 type: docs
 order: 5
+category: 'Docs'
 ---
 
 <!-- md contributing.md -->

website/src/docs/dashboard.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 30
+order: 0
 title: "Dashboard"
 module: "@uppy/dashboard"
 permalink: docs/dashboard/
+category: 'UI Elements'
 ---
 
 `@uppy/dashboard` is a universal UI plugin for Uppy, offering several useful features:

website/src/docs/dragdrop.md

@@ -1,10 +1,11 @@
 ---
 type: docs
-order: 31
+order: 1
 title: "Drag & Drop"
 module: "@uppy/drag-drop"
 permalink: docs/drag-drop/
 alias: docs/dragdrop/
+category: 'Sources'
 ---
 
 The `@uppy/drag-drop` plugin renders a simple drag and drop area for file selection. it can be useful when you only want the local device as a file source, don’t need file previews and a UI for metadata editing, and the [Dashboard](/docs/dashboard/) feels like overkill.

website/src/docs/dropbox.md

@@ -1,9 +1,11 @@
 ---
 type: docs
-order: 41
+order: 11
 title: "Dropbox"
+menu_prefix: "<span title='Requires Companion'>ⓒ </span>"
 module: "@uppy/dropbox"
 permalink: docs/dropbox/
+category: 'Sources'
 ---
 
 The `@uppy/dropbox` plugin lets users import files from their Dropbox account.

website/src/docs/fileinput.md

@@ -1,11 +1,11 @@
 ---
 type: docs
-order: 32
+order: 2
 title: "File Input"
 module: "@uppy/file-input"
 permalink: docs/file-input/
 alias: docs/fileinput/
-
+category: 'Sources'
 ---
 
 `@uppy/file-input` is the most barebones UI for selecting files — it shows a single button that, when clicked, opens up the browser's file selector.

website/src/docs/form.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 80
+order: 0
 title: "Form"
 module: "@uppy/form"
 permalink: docs/form/
+category: 'Miscellaneous'
 ---
 
 The `@uppy/form` plugin has several features to integrate with HTML `<form>` elements.

website/src/docs/golden-retriever.md

@@ -3,7 +3,8 @@ title: "Golden Retriever"
 module: "@uppy/golden-retriever"
 type: docs
 permalink: docs/golden-retriever/
-order: 81
+order: 1
+category: 'Miscellaneous'
 ---
 
 The `@uppy/golden-retriever` plugin saves selected files in your browser cache, so that if the browser crashes, Uppy can restore everything and continue uploading as if nothing happened. You can read more about it [on our blog](https://uppy.io/blog/2017/07/golden-retriever/).

website/src/docs/google-drive.md

@@ -1,9 +1,11 @@
 ---
 type: docs
-order: 42
+order: 12
 title: "Google Drive"
+menu_prefix: "<span title='Requires Companion'>ⓒ </span>"
 module: "@uppy/google-drive"
 permalink: docs/google-drive/
+category: 'Sources'
 ---
 
 The `@uppy/google-drive` plugin lets users import files from their Google Drive account.

website/src/docs/index.md

@@ -4,6 +4,7 @@ type: docs
 permalink: docs/
 alias: api/
 order: 0
+category: 'Docs'
 ---
 
 Uppy is a sleek and modular file uploader. It fetches files from local disk, Google Drive, Instagram, remote urls, cameras etc, and then uploads them to the final destination. It’s fast, easy to use and lets you worry about more important problems than building a file uploader.

website/src/docs/informer.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 62
+order: 2
 title: "Informer"
 module: "@uppy/informer"
 permalink: docs/informer/
+category: 'UI Elements'
 ---
 
 The `@uppy/informer` plugin is a pop-up bar for showing notifications. When plugins have some exciting news (or error) to share, they can show a notification here.

website/src/docs/instagram.md

@@ -1,9 +1,11 @@
 ---
 type: docs
-order: 43
+order: 13
 title: "Instagram"
+menu_prefix: "<span title='Requires Companion'>ⓒ </span>"
 module: "@uppy/instagram"
 permalink: docs/instagram/
+category: 'Sources'
 ---
 
 The `@uppy/instagram` plugin lets users import files from their Instagram account.

website/src/docs/plugins.md

@@ -2,7 +2,8 @@
 title: "List & Common Options"
 type: docs
 permalink: docs/plugins/
-order: 20
+order: 0
+category: 'Plugins'
 ---
 
 Plugins are what makes Uppy useful: they help select, manipulate and upload files.

website/src/docs/progressbar.md

@@ -1,10 +1,11 @@
 ---
 type: docs
-order: 61
+order: 1
 title: "Progress Bar"
 module: "@uppy/progress-bar"
 permalink: docs/progress-bar/
 alias: docs/progressbar/
+category: 'UI Elements'
 ---
 
 `@uppy/progress-bar` is a minimalist plugin that shows the current upload progress in a thin bar element, similar to the ones used by YouTube and GitHub when navigating between pages.

website/src/docs/providers.md

@@ -2,7 +2,8 @@
 title: "Provider Plugins"
 type: docs
 permalink: docs/providers/
-order: 40
+order: 10
+category: 'Sources'
 ---
 
 The Provider plugins help you connect to your accounts with remote file providers such as [Dropbox](https://dropbox.com), [Google Drive](https://drive.google.com), [Instagram](https://instagram.com) and remote URLs (importing a file by pasting a direct link to it). Because this requires server-to-server communication, they work tightly with [Companion](https://github.com/transloadit/companion) to manage the server-to-server authorization for your account. Almost all of the communication (file download/upload) is done on the server-to-server end, so this saves you the stress and bills of data consumption on the client.

website/src/docs/react-dashboard-modal.md

@@ -2,7 +2,8 @@
 title: "<DashboardModal />"
 type: docs
 permalink: docs/react/dashboard-modal/
-order: 95
+order: 5
+category: 'React'
 ---
 
 The `<DashboardModal />` component wraps the [`@uppy/dashboard`][] plugin, allowing control over the modal `open` state using a prop.

website/src/docs/react-dashboard.md

@@ -2,7 +2,8 @@
 title: "<Dashboard />"
 type: docs
 permalink: docs/react/dashboard/
-order: 94
+order: 4
+category: 'React'
 ---
 
 The `<Dashboard />` component wraps the [`@uppy/dashboard`][] plugin. It only renders the Dashboard inline. To use the Dashboard modal (`inline: false`), use the [`<DashboardModal />`](/docs/react/dashboard-modal) component.

website/src/docs/react-dragdrop.md

@@ -3,7 +3,8 @@ title: "<DragDrop />"
 type: docs
 permalink: docs/react/drag-drop/
 alias: docs/react/dragdrop/
-order: 92
+order: 2
+category: 'React'
 ---
 
 The `<DragDrop />` component wraps the [`@uppy/drag-drop`][] plugin.

website/src/docs/react-progressbar.md

@@ -3,7 +3,8 @@ title: "<ProgressBar />"
 type: docs
 permalink: docs/react/progress-bar/
 alias: docs/react/progressbar/
-order: 93
+order: 3
+category: 'React'
 ---
 
 The `<ProgressBar />` component wraps the [`@uppy/progress-bar`][] plugin.

website/src/docs/react-statusbar.md

@@ -3,7 +3,8 @@ title: "<StatusBar />"
 type: docs
 permalink: docs/react/status-bar/
 alias: docs/react/statusbar/
-order: 91
+order: 1
+category: 'React'
 ---
 
 The `<StatusBar />` component wraps the [`@uppy/status-bar`][] plugin.

website/src/docs/react.md

@@ -2,7 +2,8 @@
 title: "Introduction"
 type: docs
 permalink: docs/react/
-order: 90
+order: 0
+category: 'React'
 ---
 
 Uppy provides [React][] components for the included UI plugins.

website/src/docs/redux.md

@@ -2,7 +2,8 @@
 title: "Redux"
 type: docs
 permalink: docs/redux/
-order: 97
+order: 9
+category: 'React'
 ---
 
 Uppy supports the popular [Redux](https://redux.js.org/) state management library in two ways:

website/src/docs/robodog-form.md

@@ -1,9 +1,10 @@
 ---
 type: docs
 title: "Robodog: Form API"
-menu: "Form"
+menu: "Robodog Form"
 permalink: docs/robodog/form/
-order: 102
+order: 2
+category: 'File Processing'
 ---
 
 Add resumable uploads and Transloadit's processing to your existing HTML upload forms. Selected files will be uploaded to Transloadit, and the Assembly information will be submitted to your form endpoint.

website/src/docs/robodog-picker.md

@@ -1,9 +1,10 @@
 ---
 type: docs
 title: "Robodog: File Picker API"
-menu: "File Picker"
+menu: "Robodog File Picker"
 permalink: docs/robodog/picker/
-order: 101
+order: 1
+category: 'File Processing'
 ---
 
 Show a modal UI that allows users to pick files from their device and from the web. It uploads files to Transloadit for processing.

website/src/docs/robodog-upload.md

@@ -1,9 +1,10 @@
 ---
 type: docs
 title: "Robodog: Upload API"
-menu: "Upload"
+menu: "Robodog Upload"
 permalink: docs/robodog/upload/
-order: 103
+order: 3
+category: 'File Processing'
 ---
 
 Upload files straight to Transloadit from your own custom UI. Give us an array of files, and we'll give you an array of results!

website/src/docs/robodog.md

@@ -1,10 +1,11 @@
 ---
 type: docs
-order: 100
+order: 0
 title: "Robodog"
-menu: "Introduction"
+menu: "Robodog Introduction"
 module: "@uppy/robodog"
 permalink: docs/robodog/
+category: 'File Processing'
 ---
 
 [Transloadit][transloadit] is a service that helps you handle file uploads, resize, crop and watermark your images, make GIFs, transcode your videos, extract thumbnails, generate audio waveforms, and so much more. In short, [Transloadit][transloadit] is the Swiss Army Knife for your files.

website/src/docs/statusbar.md

@@ -1,10 +1,11 @@
 ---
 type: docs
-order: 60
+order: 0
 title: "Status Bar"
 module: "@uppy/status-bar"
 permalink: docs/status-bar/
 alias: docs/statusbar/
+category: 'UI Elements'
 ---
 
 The `@uppy/status-bar` plugin shows upload progress and speed, ETAs, pre- and post-processing information, and allows users to control (pause/resume/cancel) the upload.

website/src/docs/stores.md

@@ -3,6 +3,7 @@ type: docs
 order: 3
 title: "Custom Stores"
 permalink: docs/stores/
+category: 'Docs'
 ---
 
 > This section concerns storing the internal application state, if you work with React/Redux, for example. If none of this rings a bell, you can safely skip this section.

website/src/docs/transloadit.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 70
+order: 10
 title: "Transloadit"
 module: "@uppy/transloadit"
 permalink: docs/transloadit/
+category: 'File Processing'
 ---
 
 The `@uppy/transloadit` plugin can be used to upload files to [Transloadit](https://transloadit.com/) for all kinds of processing, such as transcoding video, resizing images, zipping/unzipping, [and much more](https://transloadit.com/services/).

website/src/docs/tus.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 50
+order: 0
 title: "Tus"
 module: "@uppy/tus"
 permalink: docs/tus/
+category: 'Destinations'
 ---
 
 The `@uppy/tus` plugin brings resumable file uploading by [tus.io](http://tus.io) to Uppy by wrapping the [tus-js-client][].

website/src/docs/uppy.md

@@ -4,6 +4,7 @@ order: 1
 title: "Uppy"
 module: "@uppy/core"
 permalink: docs/uppy/
+category: 'Docs'
 ---
 
 This is the core module that orchestrates everything in Uppy, managing state and events and providing methods.

website/src/docs/url.md

@@ -1,9 +1,11 @@
 ---
 type: docs
-order: 44
+order: 14
 title: "Import From URL"
+menu_prefix: "<span title='Requires Companion'>ⓒ </span>"
 module: "@uppy/url"
 permalink: docs/url/
+category: 'Sources'
 ---
 
 The `@uppy/url` plugin allows users to import files from the internet. Paste any URL and it will be added!

website/src/docs/webcam.md

@@ -1,9 +1,10 @@
 ---
 type: docs
-order: 36
+order: 3
 title: "Webcam"
 module: "@uppy/webcam"
 permalink: docs/webcam/
+category: 'Sources'
 ---
 
 The `@uppy/webcam` plugin lets you take photos and record videos with a built-in camera on desktop and mobile devices.

website/src/docs/writing-plugins.md

@@ -2,7 +2,8 @@
 type: docs
 title: "Writing Plugins"
 permalink: docs/writing-plugins/
-order: 21
+order: 1
+category: 'Plugins'
 ---
 
 There are already a few useful Uppy plugins out there, but there might come a time when you will want to build your own. Plugins can hook into the upload process or render a custom UI, typically to:

website/src/docs/xhrupload.md

@@ -1,10 +1,12 @@
 ---
 type: docs
-order: 51
+order: 1
 title: "XHR Upload"
+menu: "XHR"
 module: "@uppy/xhr-upload"
 permalink: docs/xhr-upload/
 alias: docs/xhrupload/
+category: 'Destinations'
 ---
 
 The `@uppy/xhr-upload` plugin handles classic HTML multipart form uploads, as well as uploads using the HTTP `PUT` method.

website/src/examples/bundle/index.ejs

@@ -2,6 +2,7 @@
 title: Bundle
 layout: example
 order: 2
+category: 'Examples'
 ---
 
 {% blockquote %}

website/src/examples/dashboard/index.ejs

@@ -3,6 +3,7 @@ title: Dashboard
 layout: example
 type: examples
 order: 0
+category: 'Examples'
 ---
 
 {% blockquote %}

website/src/examples/dragdrop/index.ejs

@@ -3,6 +3,7 @@ title: Drag and Drop
 layout: example
 type: examples
 order: 1
+category: 'Examples'
 ---
 
 {% blockquote %}

website/src/examples/i18n/index.ejs

@@ -2,6 +2,7 @@
 title: Bundle & i18n
 layout: example
 type: examples
+category: 'Examples'
 order: 4
 ---
 

website/src/examples/markdown-snippets/index.ejs

@@ -2,7 +2,8 @@
 title: Robodog Markdown Snippets
 layout: example
 type: examples
-order: 6
+order: 0
+category: 'File Processing'
 ---
 
 {% blockquote %}

website/src/examples/statusbar/index.ejs

@@ -3,6 +3,7 @@ title: Status Bar
 layout: example
 type: examples
 order: 5
+category: 'Examples'
 ---
 
 {% blockquote %}

website/src/examples/transloadit/index.ejs

@@ -2,7 +2,8 @@
 title: Transloadit
 layout: example
 type: examples
-order: 5
+order: 1
+category: 'File Processing'
 ---
 
 {% blockquote %}

website/src/examples/xhrupload/index.ejs

@@ -3,6 +3,7 @@ title: XHR Upload
 layout: example
 type: examples
 order: 3
+category: 'Examples'
 alias: /examples/multipart/
 ---
 

website/src/stats.ejs

@@ -2,6 +2,7 @@
 title: Stats
 type: docs
 layout: stats
+category: 'Docs'
 permalink: docs/stats/
 alias:
   - guide/stats/

website/themes/uppy/layout/partials/sidebar.ejs

@@ -1,24 +1,34 @@
 <%
-var categories = [
-  // order: 2x
-  { path: 'docs/plugins/', name: 'Plugins', link: true },
-  // order: 3x
-  { path: 'docs/dashboard/', name: 'Local Sources', link: false },
-  // order: 4x
-  { path: 'docs/providers/', name: 'Remote Providers', link: true },
-  // order: 5x
-  { path: 'docs/tus/', name: 'Uploaders', link: false },
-  // order: 6x
-  { path: 'docs/status-bar/', name: 'UI Elements', link: false },
-  // order: 7x
-  { path: 'docs/transloadit/', name: 'File Processing', link: false },
-  // order: 8x
-  { path: 'docs/form/', name: 'Miscellaneous', link: false },
-  // order: 9x
-  { path: 'docs/react/', name: 'React Components', link: true },
-  // order: 10x
-  { path: 'docs/robodog/', name: 'Robodog', link: true }
-]
+var categories = []
+
+if (page.type === 'docs') {
+  categories = [
+    { category: 'Docs', path: 'docs/', link: true, hidden: true },
+    { category: 'Plugins', path: 'docs/plugins/', link: true },
+    { category: 'UI Elements', path: 'docs/dashboard/', link: false },
+    { category: 'Sources', path: 'docs/drag-drop/', link: false },
+    { category: 'Destinations', path: 'docs/tus/', link: false },
+    { category: 'File Processing', path: 'docs/robodog/', link: true },
+    { category: 'Miscellaneous', path: 'docs/form/', link: false },
+    { category: 'React', path: 'docs/react/', link: true },
+    ]
+  } else if (page.type === 'examples') {
+    categories = [
+    { category: 'Examples', path: 'examples/', link: true, hidden: true },
+    { category: 'File Processing', path: 'examples/markdown-snippets/', link: true },
+  ]
+} else {
+  categories = [
+    { category: 'Unknown Type: ' + page.type, path: 'unknown/unknown/', link: false },
+  ]
+}
+
+var catPages = {}
+site.pages.find({ type }).each((p) => {
+  var path = (p.path || '').replace(/index\.html$/, '');
+  catPages[p.category] = catPages[p.category] || [];
+  catPages[p.category].push(p);
+})
 %>
 <div class="Sidebar js-Sidebar">
   <ul class="main-menu">
@@ -30,30 +40,30 @@ var categories = [
         <a href="/<%- type %>"><%- type === 'api' ? 'API' : (type.charAt(0).toUpperCase() + type.slice(1)) %></a>
       <% } %>
     </h2>
+
     <ul class="menu-root">
-      <% site.pages.find({ type }).sort('order').each((p) => { %>
-        <% if (p.hidden) return; %>
-        <% var path = p.path.replace(/index\.html$/, ''); %>
-        <% var category = categories.find((c) => c.path === path) %>
-        <% // see https://github.com/vuejs/vuejs.org/blob/master/themes/vue/layout/partials/toc.ejs %>
-        <% if (category) { %>
+      <% for (var i in categories) { %>
+        <% var sorted = (catPages[categories[i].category] || ['No catPages for: ' + i]).sort((a, b) => {return a.order - b.order}) %>
+        <% if (!categories[i].hidden) { %>
           <li>
-            <% if (category.link) { %>
-              <h3><a href="/<%- category.path %>"><%- category.name %></a></h3>
+            <% if (categories[i].link) { %>
+            <h3><a href="/<%- categories[i].path %>"><%- categories[i].category %></a></h3>
             <% } else { %>
-              <h3><%- category.name %></h3>
+            <h3><%- categories[i].category %></h3>
             <% } %>
           </li>
+        <% } %>
+        <% sorted.forEach((p) => { %>
+          <% var path = (p.path || '').replace(/index\.html$/, ''); %>
+          <% var firstInCategory = categories.find((c) => c.path === path) %>
+          <% // see https://github.com/vuejs/vuejs.org/blob/master/themes/vue/layout/partials/toc.ejs %>
           <li>
-            <a href="/<%- path %>" class="sidebar-link<%- page.title === p.title ? ' current' : '' %><%- p.is_new ? ' new' : '' %>"><%- p.menu || p.title %></a>
-          </li>
-        <% } else { %>
-          <li>
-            <a href="/<%- path %>" class="sidebar-link<%- page.title === p.title ? ' current' : '' %><%- p.is_new ? ' new' : '' %>"><%- p.menu || p.title %></a>
+            <%- p.menu_prefix %><a href="/<%- path %>" class="sidebar-link<%- page.title === p.title ? ' current' : '' %>"><%- p.menu || p.title %></a>
           </li>
-        <% } %>
-      <% }) %>
+        <% }) %>
+      <% } %>
     </ul>
     <%- partial('partials/social') %>
   </div>
 </div>
+

website/themes/uppy/source/css/_page.scss

@@ -80,6 +80,16 @@
     margin: 0.8em 0;
   }
 
+  ul.menu-root {
+    hr {
+      margin-top: -4px;
+      margin-bottom: 4px;
+      width: 85%;
+      border: 1px solid #e9e9e9;
+      margin-left: -1px;
+    }
+  }
+
   .sidebar-link {
     color: $color-light;