From 5d6dc49bcdd1f4476113bdb7fb0a374528c4a46d Mon Sep 17 00:00:00 2001 From: Yangshun Tay Date: Sun, 28 Apr 2019 20:20:24 -0700 Subject: [PATCH] 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 --- .../lib/default-theme/DocBody/index.js | 6 --- .../lib/default-theme/Navbar/index.js | 9 ---- .../lib/default-theme/Sidebar/index.js | 2 +- website/README.md | 50 ++++++++++++++++++- website/docs/TEMPLATE.md | 9 ++++ website/docs/analytics.md | 6 +++ website/docs/assets.md | 19 +++++++ website/docs/blog.md | 10 ++++ website/docs/cli.md | 10 ++++ website/docs/configuration.md | 10 ++++ website/docs/creating-pages.md | 11 ++++ website/docs/deployment.md | 10 ++++ website/docs/design-principles.md | 16 ++++++ website/docs/docusaurus-core.md | 10 ++++ website/docs/docusaurus.config.js.md | 11 ++++ website/docs/how-docusaurus-works.md | 12 +++++ website/docs/how-to-contribute.md | 10 ++++ website/docs/installation.md | 31 ++++++++++++ website/docs/introduction.md | 24 ++++++++- website/docs/markdown.md | 9 ++++ website/docs/motivation.md | 8 +++ website/docs/plugins-api.md | 10 ++++ website/docs/plugins.md | 23 +++++++++ website/docs/presets.md | 18 +++++++ website/docs/project-structure.md | 16 ++++++ website/docs/search.md | 10 ++++ website/docs/styling-layout.md | 10 ++++ website/docs/themes.md | 22 ++++++++ website/docs/using-plugins.md | 11 ++++ website/docs/using-themes.md | 10 ++++ website/docs/writing-documentation.md | 11 ++++ website/docusaurus.config.js | 13 +---- website/sidebars-legacy.json | 25 ---------- website/sidebars.js | 37 ++++++++++++++ website/sidebars.json | 7 --- 35 files changed, 443 insertions(+), 63 deletions(-) create mode 100644 website/docs/TEMPLATE.md create mode 100644 website/docs/analytics.md create mode 100644 website/docs/assets.md create mode 100644 website/docs/blog.md create mode 100644 website/docs/cli.md create mode 100644 website/docs/configuration.md create mode 100644 website/docs/creating-pages.md create mode 100644 website/docs/deployment.md create mode 100644 website/docs/design-principles.md create mode 100644 website/docs/docusaurus-core.md create mode 100644 website/docs/docusaurus.config.js.md create mode 100644 website/docs/how-docusaurus-works.md create mode 100644 website/docs/how-to-contribute.md create mode 100644 website/docs/installation.md create mode 100644 website/docs/markdown.md create mode 100644 website/docs/motivation.md create mode 100644 website/docs/plugins-api.md create mode 100644 website/docs/plugins.md create mode 100644 website/docs/presets.md create mode 100644 website/docs/project-structure.md create mode 100644 website/docs/search.md create mode 100644 website/docs/styling-layout.md create mode 100644 website/docs/themes.md create mode 100644 website/docs/using-plugins.md create mode 100644 website/docs/using-themes.md create mode 100644 website/docs/writing-documentation.md delete mode 100644 website/sidebars-legacy.json create mode 100644 website/sidebars.js delete mode 100644 website/sidebars.json diff --git a/packages/docusaurus/lib/default-theme/DocBody/index.js b/packages/docusaurus/lib/default-theme/DocBody/index.js index 786b712a59..4439f22a69 100644 --- a/packages/docusaurus/lib/default-theme/DocBody/index.js +++ b/packages/docusaurus/lib/default-theme/DocBody/index.js @@ -45,12 +45,6 @@ function DocBody(props) {
- {/* TODO: remove this in the future */} -
- Docusaurus 2 is still work in progress. Do not - use it in production yet! -
-

{metadata.title}

diff --git a/packages/docusaurus/lib/default-theme/Navbar/index.js b/packages/docusaurus/lib/default-theme/Navbar/index.js index b817fcb5bb..b502679734 100644 --- a/packages/docusaurus/lib/default-theme/Navbar/index.js +++ b/packages/docusaurus/lib/default-theme/Navbar/index.js @@ -95,15 +95,6 @@ function Navbar(props) {
)} -
- - - -
diff --git a/packages/docusaurus/lib/default-theme/Sidebar/index.js b/packages/docusaurus/lib/default-theme/Sidebar/index.js index 0068b1ec13..1bf932dffc 100644 --- a/packages/docusaurus/lib/default-theme/Sidebar/index.js +++ b/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.`, ); } diff --git a/website/README.md b/website/README.md index 2641e9d096..a26dd87a2f 100644 --- a/website/README.md +++ b/website/README.md @@ -1 +1,49 @@ -## Docusaurus 2 Website \ No newline at end of file +# 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 +``` diff --git a/website/docs/TEMPLATE.md b/website/docs/TEMPLATE.md new file mode 100644 index 0000000000..8a78d92ad1 --- /dev/null +++ b/website/docs/TEMPLATE.md @@ -0,0 +1,9 @@ +--- +id: TODO +title: TODO +--- + + +#### References + +- TODO diff --git a/website/docs/analytics.md b/website/docs/analytics.md new file mode 100644 index 0000000000..159752ef62 --- /dev/null +++ b/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). diff --git a/website/docs/assets.md b/website/docs/assets.md new file mode 100644 index 0000000000..6907238819 --- /dev/null +++ b/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/ diff --git a/website/docs/blog.md b/website/docs/blog.md new file mode 100644 index 0000000000..cebc94f324 --- /dev/null +++ b/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 diff --git a/website/docs/cli.md b/website/docs/cli.md new file mode 100644 index 0000000000..0fe0d5366a --- /dev/null +++ b/website/docs/cli.md @@ -0,0 +1,10 @@ +--- +id: cli +title: CLI +--- + +TODO: Add CLI reference here. + +#### References + +- TODO diff --git a/website/docs/configuration.md b/website/docs/configuration.md new file mode 100644 index 0000000000..c95b2c0881 --- /dev/null +++ b/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 diff --git a/website/docs/creating-pages.md b/website/docs/creating-pages.md new file mode 100644 index 0000000000..b0465f771c --- /dev/null +++ b/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/ diff --git a/website/docs/deployment.md b/website/docs/deployment.md new file mode 100644 index 0000000000..4377a88e61 --- /dev/null +++ b/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/ diff --git a/website/docs/design-principles.md b/website/docs/design-principles.md new file mode 100644 index 0000000000..a487918090 --- /dev/null +++ b/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 diff --git a/website/docs/docusaurus-core.md b/website/docs/docusaurus-core.md new file mode 100644 index 0000000000..cad05dd0b6 --- /dev/null +++ b/website/docs/docusaurus-core.md @@ -0,0 +1,10 @@ +--- +id: docusaurus-core +title: Docusaurus Core +--- + +TODO: Mention Docusaurus core APIs here, such as ``, ``, `prefetch`, etc. + +#### References + +- TODO diff --git a/website/docs/docusaurus.config.js.md b/website/docs/docusaurus.config.js.md new file mode 100644 index 0000000000..161137dac1 --- /dev/null +++ b/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/ diff --git a/website/docs/how-docusaurus-works.md b/website/docs/how-docusaurus-works.md new file mode 100644 index 0000000000..114d748d3b --- /dev/null +++ b/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/ diff --git a/website/docs/how-to-contribute.md b/website/docs/how-to-contribute.md new file mode 100644 index 0000000000..b940968798 --- /dev/null +++ b/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 diff --git a/website/docs/installation.md b/website/docs/installation.md new file mode 100644 index 0000000000..1f5c5140e2 --- /dev/null +++ b/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! diff --git a/website/docs/introduction.md b/website/docs/introduction.md index 604d9ec5ac..076ce81607 100644 --- a/website/docs/introduction.md +++ b/website/docs/introduction.md @@ -3,13 +3,33 @@ id: introduction title: Introduction --- +
+ Docusaurus 2 is still work in progress. Do not use it in production yet! +
![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/ diff --git a/website/docs/markdown.md b/website/docs/markdown.md new file mode 100644 index 0000000000..6e307b1608 --- /dev/null +++ b/website/docs/markdown.md @@ -0,0 +1,9 @@ +--- +id: markdown +title: Markdown Features +--- + + +#### References + +- TODO diff --git a/website/docs/motivation.md b/website/docs/motivation.md new file mode 100644 index 0000000000..5b1099a5ff --- /dev/null +++ b/website/docs/motivation.md @@ -0,0 +1,8 @@ +--- +id: motivation +title: Motivation +--- + +#### References + +- https://redux.js.org/introduction/motivation diff --git a/website/docs/plugins-api.md b/website/docs/plugins-api.md new file mode 100644 index 0000000000..c388e6d91c --- /dev/null +++ b/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 diff --git a/website/docs/plugins.md b/website/docs/plugins.md new file mode 100644 index 0000000000..a8f5d1a570 --- /dev/null +++ b/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/ diff --git a/website/docs/presets.md b/website/docs/presets.md new file mode 100644 index 0000000000..8055db4525 --- /dev/null +++ b/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 diff --git a/website/docs/project-structure.md b/website/docs/project-structure.md new file mode 100644 index 0000000000..f573203b83 --- /dev/null +++ b/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 diff --git a/website/docs/search.md b/website/docs/search.md new file mode 100644 index 0000000000..9204547dfe --- /dev/null +++ b/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 diff --git a/website/docs/styling-layout.md b/website/docs/styling-layout.md new file mode 100644 index 0000000000..a491d81a0f --- /dev/null +++ b/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/ diff --git a/website/docs/themes.md b/website/docs/themes.md new file mode 100644 index 0000000000..a7782995e4 --- /dev/null +++ b/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/ diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md new file mode 100644 index 0000000000..fe2f72271e --- /dev/null +++ b/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/ diff --git a/website/docs/using-themes.md b/website/docs/using-themes.md new file mode 100644 index 0000000000..fe01bf4938 --- /dev/null +++ b/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/ diff --git a/website/docs/writing-documentation.md b/website/docs/writing-documentation.md new file mode 100644 index 0000000000..bc33dafde8 --- /dev/null +++ b/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 diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index ac63f09151..edcff5aac1 100644 --- a/website/docusaurus.config.js +++ b/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'), - }, - }, - ], }; diff --git a/website/sidebars-legacy.json b/website/sidebars-legacy.json deleted file mode 100644 index 632546c139..0000000000 --- a/website/sidebars-legacy.json +++ /dev/null @@ -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" - ] - } -} diff --git a/website/sidebars.js b/website/sidebars.js new file mode 100644 index 0000000000..fa962680f4 --- /dev/null +++ b/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'], + }, +}; diff --git a/website/sidebars.json b/website/sidebars.json deleted file mode 100644 index 8ba4ef3427..0000000000 --- a/website/sidebars.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "docs": { - "Quick Start": [ - "introduction" - ] - } -}