docs(v2): add docs skeleton and structure (#1412)

* docs(v2): add docs skeleton and structure

* docs(v2): add on

* docs(v2): move motivation into contributing

packages/docusaurus/lib/default-theme/DocBody/index.js

@@ -45,12 +45,6 @@ function DocBody(props) {
       <div className="container margin-vert--lg">
         <div className="row">
           <div className="col col--8">
-            {/* TODO: remove this in the future */}
-            <div className="alert alert--warning" role="alert">
-              Docusaurus 2 is still <strong>work in progress</strong>. Do not
-              use it in production yet!
-            </div>
-            <br />
             <header>
               <h1 className="margin-bottom--lg">{metadata.title}</h1>
             </header>

packages/docusaurus/lib/default-theme/Navbar/index.js

@@ -95,15 +95,6 @@ function Navbar(props) {
               <Search {...props} />
             </div>
           )}
-          <div className="navbar__item">
-            <a
-              className="navbar__link"
-              href="https://github.com/facebook/docusaurus"
-              rel="noopener noreferrer"
-              target="_blank">
-              <i className="fab fa-github fa-lg" />
-            </a>
-          </div>
         </div>
       </div>
     </nav>

packages/docusaurus/lib/default-theme/Sidebar/index.js

@@ -36,7 +36,7 @@ function Sidebar(props) {
 
     if (!linkMetadata) {
       throw new Error(
-        `Improper sidebars.json file, document with id '${linkID}' not found.`,
+        `Improper sidebars file, document with id '${linkID}' not found.`,
       );
     }
 

website/README.md

@@ -1 +1,49 @@
-## Docusaurus 2 Website
+# Docusaurus 2 Website
+
+## Installation
+
+1. `yarn install` in the root of the repo (one level above this directory).
+1. In this directory, do `yarn start`.
+1. A browser window will open up, pointing to the docs.
+
+### Information Hierarchy
+
+This is a high-level overview of the content of the docs:
+
+```
+├─ Getting Started
+│  ├─ Introduction
+│  ├─ Motivation
+│  ├─ Installation
+│  ├─ Project Structure
+│  └─ Deployment
+│
+├─ Guides
+│  ├─ Configuration
+│  ├─ Creating Pages
+│  ├─ Writing Documentation
+│  ├─ Using Assets
+│  ├─ Markdown Features
+│  ├─ Styling and Layout
+│  ├─ Using Plugins
+│  ├─ Using Themes
+│  ├─ Adding Search
+│  └─ Adding Analytics
+│
+├─ Advanced Guides
+│  ├─ Blog
+│  ├─ Plugins
+│  ├─ Themes
+│  ├─ Presets
+│  └─ How Docusaurus Works
+│
+├─ API Reference
+│  ├─ CLI
+│  ├─ Docusaurus core
+│  ├─ docusaurus.config.js
+│  └─ Plugins
+│
+├─ Contributing
+│  ├─ How to Contribute
+│  └─ Design Principles
+```

website/docs/TEMPLATE.md

@@ -0,0 +1,9 @@
+---
+id: TODO
+title: TODO
+---
+
+
+#### References
+
+- TODO

website/docs/analytics.md

@@ -0,0 +1,6 @@
+---
+id: analytics
+title: Adding Analytics
+---
+
+TODO: Talk about how to add Algolia search and offline search via the search plugin (TBD).

website/docs/assets.md

@@ -0,0 +1,19 @@
+---
+id: assets
+title: Using Assets
+---
+
+TODO: Talk about how to include static assets within pages and docs.
+
+### Images
+
+TODO: How to include images in the website and reference them from pages and docs.
+
+### Videos
+
+TODO: Show how to easily embed YouTube videos.
+
+#### References
+
+- https://v1.vuepress.vuejs.org/guide/assets.html
+- https://www.gatsbyjs.org/docs/images-and-files/

website/docs/blog.md

@@ -0,0 +1,10 @@
+---
+id: blog
+title: Blog
+---
+
+TODO: Explain how to add a blog and using the blog plugin.
+
+#### References
+
+- TODO

website/docs/cli.md

@@ -0,0 +1,10 @@
+---
+id: cli
+title: CLI
+---
+
+TODO: Add CLI reference here.
+
+#### References
+
+- TODO

website/docs/configuration.md

@@ -0,0 +1,10 @@
+---
+id: configuration
+title: Configuration
+---
+
+TODO: Cover the mandatory configuration options here.
+
+#### References
+
+- https://v1.vuepress.vuejs.org/guide/basic-config.html

website/docs/creating-pages.md

@@ -0,0 +1,11 @@
+---
+id: creating-pages
+title: Creating Pages
+---
+
+TODO: Explain the default pages routing behavior and talk about the official pages plugin.
+
+#### References
+
+- https://docusaurus.io/docs/en/custom-pages
+- https://www.gatsbyjs.org/docs/creating-and-modifying-pages/

website/docs/deployment.md

@@ -0,0 +1,10 @@
+---
+id: deployment
+title: Deployment
+---
+
+TODO: Talk about deployment steps and different hosting options.
+
+#### References
+
+- https://www.gatsbyjs.org/docs/deploying-and-hosting/

website/docs/design-principles.md

@@ -0,0 +1,16 @@
+---
+id: design-principles
+title: Design Principles
+---
+
+- Easy to learn but most things are still achievable by users, even if it takes them more code and more time to write. No abstractions beat bad abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk: Minimal API Surface Area
+- Users won't feel overwhelmed when looking at the directory of a D2 project. It just makes sense and is easy to build on top of. Gatsby projects have a ton of config files - `gatsby-config.js`, `gatsby-node.js`, `gatsby-client.js`, which can look intimidating to beginners.
+- We should not lock in our users to use our plugins or our CSS. Certain lower-level infra level stuff like React Loadable, React Router are fine, but not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology.
+- The separations of concerns between each layer of our stack should be clear - well-abstracted and modular.
+
+TODO: Explain the principles that guide the development of Docusaurus.
+
+#### References
+
+- https://reactjs.org/docs/design-principles.html
+- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html

website/docs/docusaurus-core.md

@@ -0,0 +1,10 @@
+---
+id: docusaurus-core
+title: Docusaurus Core
+---
+
+TODO: Mention Docusaurus core APIs here, such as `<Link />`, `<Head />`, `prefetch`, etc.
+
+#### References
+
+- TODO

website/docs/docusaurus.config.js.md

@@ -0,0 +1,11 @@
+---
+id: docusaurus.config.js
+title: docusaurus.config.js
+---
+
+TODO: Explain the various `docusaurus.config.js` options.
+
+#### References
+
+- https://docusaurus.io/docs/en/site-config
+- https://v1.vuepress.vuejs.org/config/

website/docs/how-docusaurus-works.md

@@ -0,0 +1,12 @@
+---
+id: TODO
+title: TODO
+---
+
+We believe that as devlopers, 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.
+
+TODO: Elaborate more.
+
+#### References
+
+- https://www.gatsbyjs.org/docs/behind-the-scenes/

website/docs/how-to-contribute.md

@@ -0,0 +1,10 @@
+---
+id: how-to-contribute
+title: How to Contribute
+---
+
+TODO: Basically mirror the `CONTRIBUTING.md` that we have.
+
+#### References
+
+- https://reactjs.org/docs/how-to-contribute.html

website/docs/installation.md

@@ -0,0 +1,31 @@
+---
+id: installation
+title: Installation
+---
+
+Docusaurus is a website generator that runs on the React ecosystem that is great for building static content such as project documentation, your personal home page, a portfolio. However, if you're not using advanced features, you don't have to know much React at all as you can use the default templates and write your content in Markdown.
+
+## Installation
+
+TODO
+
+### New Project
+
+TODO: Mention tutorial
+
+### Adding to an Existing Project
+
+TODO
+
+## Staying Informed
+
+TODO
+
+- Twitter
+- Blog
+
+## Something Missing?
+
+If you find issues with the documentation or have suggestions on how to improve the documentation or the project in general, please [file an issue](https://github.com/facebook/docusaurus) for us, or send a tweet mentioning the [@docusaurus](https://twitter.com/docusaurus) Twitter account.
+
+For new feature requests, you can create a post on our [Canny board](/feedback), which is a handy tool for roadmapping and allows for sorting by upvotes, which gives the core team a better indicator of what features are in high demand, as compared to GitHub issues which are harder to triage. Refrain from making a Pull Request for new features (especially large ones) as someone might already be working on it or will be part of our roadmap. Talk to us first!

website/docs/introduction.md

@@ -3,13 +3,33 @@ id: introduction
 title: Introduction
 ---
 
+<div className="alert alert--warning margin-vert--md" role="alert">
+  Docusaurus 2 is still <strong>work in progress</strong>. Do not use it in production yet!
+</div>
 
 ![Introducing Slash](/img/slash-introducing.svg)
 
 Docusaurus is a **painless static site generator** powered by React.
 
-
-## Installation
+## How it Works
 
 TODO
 
+## Features
+
+TODO
+
+## Is this the right tool for you?
+
+TODO - Comparison with other tools.
+
+- Next
+- Gatsby
+- React Static
+- Jekyll
+- GitBook
+
+#### References
+
+- https://reactjs.org/docs/getting-started.html
+- https://v1.vuepress.vuejs.org/guide/

website/docs/markdown.md

@@ -0,0 +1,9 @@
+---
+id: markdown
+title: Markdown Features
+---
+
+
+#### References
+
+- TODO

website/docs/motivation.md

@@ -0,0 +1,8 @@
+---
+id: motivation
+title: Motivation
+---
+
+#### References
+
+- https://redux.js.org/introduction/motivation

website/docs/plugins-api.md

@@ -0,0 +1,10 @@
+---
+id: plugins-api
+title: Plugins
+---
+
+TODO: Plugin lifecycle APIs.
+
+#### References
+
+- https://v1.vuepress.vuejs.org/plugin/option-api.html

website/docs/plugins.md

@@ -0,0 +1,23 @@
+---
+id: plugins
+title: Plugins
+---
+
+TODO: Explain what plugins are.
+
+## What are Plugins for?
+
+TODO
+
+## How to Create Plugins
+
+TODO
+
+## Official Plugins
+
+TODO
+
+#### References
+
+- https://v1.vuepress.vuejs.org/plugin/
+- https://www.gatsbyjs.org/docs/plugins/

website/docs/presets.md

@@ -0,0 +1,18 @@
+---
+id: presets
+title: Presets
+---
+
+TODO: Explain what presets are.
+
+## Using Presets
+
+TODO: How to use presets and build your own ones to share with others.
+
+## Official Presets
+
+TODO: List them out and explain.
+
+#### References
+
+- https://babeljs.io/docs/en/presets

website/docs/project-structure.md

@@ -0,0 +1,16 @@
+---
+id: project-structure
+title: Project Structure
+---
+
+```
+// TODO: Display project directory structure
+```
+
+- TODO: Explain what each directory and files are about.
+- TODO: Explain default page routing.
+
+#### References
+
+- https://docusaurus.io/docs/en/site-creation
+- https://v1.vuepress.vuejs.org/guide/directory-structure.html

website/docs/search.md

@@ -0,0 +1,10 @@
+---
+id: search
+title: Adding Search
+---
+
+TODO: Talk about how to add Algolia search and offline search via the search plugin (TBD).
+
+#### References
+
+- https://docusaurus.io/docs/en/search

website/docs/styling-layout.md

@@ -0,0 +1,10 @@
+---
+id: styling-layout
+title: Styling and Layout
+---
+
+TODO: Go over how to add custom styling to pages and customizing layout by overriding layout components.
+
+#### References
+
+- https://www.gatsbyjs.org/docs/styling/

website/docs/themes.md

@@ -0,0 +1,22 @@
+---
+id: themes
+title: Themes
+---
+
+TODO: Explain what themes are.
+
+## What are Themes for?
+
+TODO
+
+## How to Create Themes
+
+TODO
+
+## Official Themes
+
+TODO
+
+#### References
+
+- https://v1.vuepress.vuejs.org/theme/

website/docs/using-plugins.md

@@ -0,0 +1,11 @@
+---
+id: using-plugins
+title: Using Plugins
+---
+
+TODO: Give a high-level overview about plugins and what they can be used for.
+
+#### References
+
+- https://v1.vuepress.vuejs.org/plugin/
+- https://www.gatsbyjs.org/docs/plugins/

website/docs/using-themes.md

@@ -0,0 +1,10 @@
+---
+id: using-themes
+title: Using Themes
+---
+
+TODO: Give a high-level overview about themes and what they can be used for.
+
+#### References
+
+- https://v1.vuepress.vuejs.org/theme/

website/docs/writing-documentation.md

@@ -0,0 +1,11 @@
+---
+id: writing-documentation
+title: Writing Documentation
+---
+
+TODO: Talk more about using the official docs plugin and how to configure the sidebar. Mention about incorporating assets and a preview of the cool Markdown features available, but don't list all the Markdown features here.
+
+
+#### References
+
+- https://docusaurus.io/docs/en/navigation

website/docusaurus.config.js

@@ -13,7 +13,6 @@ module.exports = {
   baseUrl: '/',
   url: 'https://docusaurus-2.netlify.com',
   headerLinks: [
-    {url: 'docs-legacy/installation', label: 'Docs V1'},
     {url: 'docs/introduction', label: 'Docs'},
     {url: 'blog', label: 'Blog'},
     {url: 'feedback/', label: 'Feedback'},
@@ -31,7 +30,7 @@ module.exports = {
       {
         docs: {
           path: 'docs',
-          sidebarPath: require.resolve('./sidebars.json'),
+          sidebarPath: require.resolve('./sidebars.js'),
         },
         blog: {
           path: '../website-1.x/blog',
@@ -39,14 +38,4 @@ module.exports = {
       },
     ],
   ],
-  plugins: [
-    {
-      name: '@docusaurus/plugin-content-docs',
-      options: {
-        path: '../docs',
-        routeBasePath: 'docs-legacy',
-        sidebarPath: require.resolve('./sidebars-legacy.json'),
-      },
-    },
-  ],
 };

website/sidebars-legacy.json

@@ -1,25 +0,0 @@
-{
-  "docs-legacy": {
-    "Getting Started": [
-      "installation",
-      "site-preparation",
-      "site-creation",
-      "publishing",
-      "docker"
-    ],
-    "Guides": [
-      "adding-blog",
-      "custom-pages",
-      "search",
-      "navigation",
-      "translation",
-      "versioning"
-    ],
-    "API": [
-      "commands",
-      "doc-markdown",
-      "api-pages",
-      "site-config"
-    ]
-  }
-}

website/sidebars.js

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  docs: {
+    'Getting Started': [
+      'introduction',
+      'installation',
+      'project-structure',
+      'deployment',
+    ],
+    Guides: [
+      'configuration',
+      'creating-pages',
+      'writing-documentation',
+      'assets',
+      'markdown',
+      'styling-layout',
+      'using-plugins',
+      'using-themes',
+      'search',
+      'analytics',
+    ],
+    'Advanced Guides': ['blog', 'plugins', 'themes', 'presets'],
+    'API Reference': [
+      'cli',
+      'docusaurus-core',
+      'docusaurus.config.js',
+      'plugins',
+    ],
+    Contributing: ['how-to-contribute', 'motivation', 'design-principles'],
+  },
+};

website/sidebars.json

@@ -1,7 +0,0 @@
-{
-  "docs": {
-    "Quick Start": [
-      "introduction"
-    ]
-  }
-}