mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 07:37:19 +02:00
docs(v2): Improve intro doc (#4770)
* Intro documentation refactoring * useless images * improve the intro doc
This commit is contained in:
Sébastien Lorber
GitHub
parent
09d107969c
commit
fe6492aa87
9 changed files with 123 additions and 84 deletions
|
|
@ -3,7 +3,7 @@ id: contributing
|
|||
title: Contributing
|
||||
---
|
||||
|
||||
[Docusaurus 2](https://docusaurus.io/) is currently under alpha development. We have [early adopters who already started using it](/showcase). We are now welcoming contributors to collaborate on the next Docusaurus.
|
||||
[Docusaurus 2](https://docusaurus.io/) is currently under development. We have [early adopters who already started using it](/showcase). We are now welcoming contributors to collaborate on the next Docusaurus.
|
||||
|
||||
The [Open Source Guides](https://opensource.guide/) website has a collection of resources for individuals, communities, and companies who want to learn how to run and contribute to an open source project. Contributors and people new to open source alike will find the following guides especially useful:
|
||||
|
||||
|
|
@ -18,7 +18,7 @@ Facebook has adopted a Code of Conduct that we expect project participants to ad
|
|||
|
||||
There are many ways to contribute to Docusaurus, and many of them do not involve writing any code. Here's a few ideas to get started:
|
||||
|
||||
- Start using Docusaurus 2! Go through the [Getting Started](installation.md) guides. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues).
|
||||
- Start using Docusaurus 2! Go through the [Getting Started](/docs/installation) guides. Does everything work as expected? If not, we're always looking for improvements. Let us know by [opening an issue](#reporting-new-issues).
|
||||
- Look through the [v2.0 issues](https://github.com/facebook/docusaurus/labels/v2). If you find an issue you would like to fix, [open a pull request](#your-first-pull-request). Issues tagged as [_Good first issue_](https://github.com/facebook/docusaurus/labels/Good%20first%20issue) are a good place to get started.
|
||||
- Help us making the docs better. File an issue if you find anything that is confusing or can be improved. We also have [an umbrella issue for v2 docs](https://github.com/facebook/docusaurus/issues/1640) where we are planning and working on all v2 docs. You may adopt a doc piece there to work on.
|
||||
- Take a look at the [features requested](https://github.com/facebook/docusaurus/labels/enhancement) by others in the community and consider opening a pull request if you see something you want to work on.
|
||||
|
|
@ -95,7 +95,7 @@ For advanced minification of CSS bundle, we use the [advanced cssnano preset](ht
|
|||
|
||||
:::caution
|
||||
|
||||
We highly discourage swizzling of components until we've reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.
|
||||
We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -1,34 +0,0 @@
|
|||
---
|
||||
id: design-principles
|
||||
title: Design Principles
|
||||
---
|
||||
|
||||
:::caution
|
||||
|
||||
This section is a work in progress.
|
||||
|
||||
:::
|
||||
|
||||
- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8).
|
||||
- **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
|
||||
- **Layered architecture** - The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular.
|
||||
- **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
|
||||
- **No vendor-lock in** - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core lower-level infra level pieces like React Loadable, React Router cannot be swapped because we do default performance optimization on them. But not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology will be entirely up to users.
|
||||
|
||||
## How Docusaurus works {#how-docusaurus-works}
|
||||
|
||||
<!-- moved in from how Docusaurus works @yangshun -->
|
||||
|
||||
We believe that as developers, 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.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
|
@ -3,11 +3,13 @@ id: installation
|
|||
title: Installation
|
||||
---
|
||||
|
||||
Docusaurus is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/master/packages) that can be installed over npm.
|
||||
Docusaurus is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/master/packages).
|
||||
|
||||
:::tip
|
||||
|
||||
Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immediately in CodeSandbox.
|
||||
Use the **[Fast Track](introduction.md#fast-track)** to understand Docusaurus in **5 minutes ⏱**!
|
||||
|
||||
Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immediately in your browser!
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -5,13 +5,54 @@ description: Docusaurus was designed from the ground up to be easily installed a
|
|||
slug: /
|
||||
---
|
||||
|
||||
⚡️ Docusaurus will help you ship a **beautiful documentation site in no time**.
|
||||
|
||||
💸 Building a custom tech stack is expensive. Instead, **focus on your content** and just write Markdown files.
|
||||
|
||||
💥 Ready for more? Use **advanced features** like versioning, i18n, search and theme customizations.
|
||||
|
||||
💅 Check the **[best Docusaurus sites](/showcase?tags=favorite)** for inspiration and read some **[testimonials](https://twitter.com/sebastienlorber/timelines/1392048416872706049)**.
|
||||
|
||||
🧐 Docusaurus is a **static-site generator**. It builds a **single-page application** with a fast client-side navigation, leveraging the full power of **React** to make your site interactive. It provides out-of-the-box **documentation features**, but can be used to create **any kind of site** (personal website, product, blog, marketing landing pages, etc).
|
||||
|
||||
|
||||
|
||||
## Fast Track ⏱️ {#fast-track}
|
||||
|
||||
Understand Docusaurus in **5 minutes** by playing!
|
||||
|
||||
Create a new Docusaurus site and follow the **very short** embedded tutorial.
|
||||
|
||||
Install [Node.js](https://nodejs.org/en/download/) and create a new Docusaurus site:
|
||||
|
||||
```bash
|
||||
npx @docusaurus/init@latest init my-website classic
|
||||
```
|
||||
|
||||
Start the site:
|
||||
|
||||
```bash
|
||||
cd my-website
|
||||
npx docusaurus start
|
||||
```
|
||||
|
||||
Open `http://localhost:3000` and follow the tutorial.
|
||||
|
||||
:::tip
|
||||
|
||||
Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immediately in your browser!
|
||||
|
||||
Or read the **[5 minutes tutorial](https://docusaurus.sse.codesandbox.io/)** online.
|
||||
|
||||
:::
|
||||
|
||||
## Disclaimer {#disclaimer}
|
||||
|
||||
Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable.
|
||||
Docusaurus v2 is **beta** but already quite stable and widely used.
|
||||
|
||||
We highly encourage you to **use Docusaurus v2 over Docusaurus v1**.
|
||||
We highly encourage you to **use Docusaurus v2 over Docusaurus v1**, as Docusaurus v1 will be deprecated soon.
|
||||
|
||||
Most users are already using v2 ([trends](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)), including [React Native](https://reactnative.dev), [Redux](https://redux.js.org/) and [many others](/showcase).
|
||||
A [lot of users](/showcase) are already using Docusaurus v2 ([trends](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)).
|
||||
|
||||
**Use Docusaurus v2 if:**
|
||||
|
||||
|
|
@ -20,46 +61,29 @@ Most users are already using v2 ([trends](https://www.npmtrends.com/docusaurus-v
|
|||
- :white_check_mark: You want the full power of React and MDX
|
||||
- :white_check_mark: You do not need support for IE11
|
||||
|
||||
:::tip
|
||||
|
||||
Use **[new.docusaurus.io](https://new.docusaurus.io)** to test Docusaurus immediately in CodeSandbox.
|
||||
|
||||
:::
|
||||
|
||||
**Use [Docusaurus v1](https://v1.docusaurus.io/) if:**
|
||||
|
||||
- :x: You don't want a single-page application (SPA)
|
||||
- :x: You prefer stability over modernity
|
||||
- :x: You need support for IE11
|
||||
|
||||
## A better Docusaurus is coming to town {#a-better-docusaurus-is-coming-to-town}
|
||||
|
||||
|
||||
|
||||
Docusaurus 1 used to be a pure documentation site generator. In Docusaurus 2, we rebuilt it from the ground up, allowing for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n (_coming soon_).
|
||||
|
||||
Beyond that, Docusaurus 2 is a **performant static site generator** and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.
|
||||
|
||||
While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.**
|
||||
|
||||
## Features {#features}
|
||||
|
||||
Docusaurus is built with high attention to your experience building your site and maintaining it with your collaborators and contributors.
|
||||
Docusaurus is built with high attention to the developer and contributor experience.
|
||||
|
||||
- ⚛️ **Built with 💚 and React**
|
||||
- Extend and customize with React
|
||||
- Gain full control of your site's browsing experience by `swizzling` in your own components
|
||||
- Gain full control of your site's browsing experience by providing your own React components
|
||||
- **Pluggable**
|
||||
- Bootstrap your site with a basic template, then pick and plug functionalities built by us and our community
|
||||
- Open source your plugins to share with your fellow documentarians, because sharing is caring
|
||||
- Bootstrap your site with a basic template, then use advanced features and plugins
|
||||
- Open source your plugins to share with the community
|
||||
- ✂️ **Developer experience**
|
||||
- Multiple bootstrapping templates to get your site up and running, start writing your docs right now
|
||||
- Start writing your docs right now
|
||||
- Universal configuration entry point to make it more maintainable by contributors
|
||||
- Hot reloading with lightning fast incremental build on changes
|
||||
- Route-based code and data splitting
|
||||
- Publish to GitHub Pages, Netlify, and other deployment services with ease
|
||||
- Publish to GitHub Pages, Netlify, Vercel and other deployment services with ease
|
||||
|
||||
Our shared goal — to help your users find what they need fast, and understand your products better. With the experience of Docusaurus 1, we share with you our best practices to help you build your doc site right and well.
|
||||
Our shared goal — to help your users find what they need fast, and understand your products better. We share with you our best practices helping you build your doc site right and well.
|
||||
|
||||
- 🎯 **SEO friendly**
|
||||
- HTML files are statically generated for every possible path
|
||||
|
|
@ -69,50 +93,91 @@ Our shared goal — to help your users find what they need fast, and understand
|
|||
- Share your code in live editors to get your users love your products on the spot
|
||||
- 🔍 **Search** - Your full site is searchable
|
||||
- 💾 **Document Versioning** - Helps you keep documentation in sync with project releases.
|
||||
- 🌍 **i18n**
|
||||
- 🌍 **i18n** - Translate your site in multiple locales
|
||||
|
||||
Docusaurus 2 is born to be compassionately accessible to all your users, and lightning fast.
|
||||
|
||||
- ⚡️ **Lightning fast** - Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast
|
||||
- 🦖 **Accessible** - Attention to accessibility, making your site equally accessible to all users
|
||||
|
||||
## Design principles {#design-principles}
|
||||
|
||||
- **Little to learn** - Docusaurus should be easy to learn and use as the API is quite small. Most things will still be achievable by users, even if it takes them more code and more time to write. Not having abstractions is better than having the wrong abstractions, and we don't want users to have to hack around the wrong abstractions. Mandatory talk - [Minimal API Surface Area](https://www.youtube.com/watch?v=4anAwXYqLG8).
|
||||
- **Intuitive** - Users will not feel overwhelmed when looking at the project directory of a Docusaurus project or adding new features. It should look intuitive and easy to build on top of, using approaches they are familiar with.
|
||||
- **Layered architecture** - The separations of concerns between each layer of our stack (content/theming/styling) should be clear - well-abstracted and modular.
|
||||
- **Sensible defaults** - Common and popular performance optimizations and configurations will be done for users but they are given the option to override them.
|
||||
- **No vendor-lock in** - Users are not required to use the default plugins or CSS, although they are highly encouraged to. Certain core lower-level infra level pieces like React Loadable, React Router cannot be swapped because we do default performance optimization on them. But not higher level ones, such as choice of Markdown engines, CSS frameworks, CSS methodology will be entirely up to users.
|
||||
|
||||
We believe that as developers, 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.
|
||||
|
||||
<!--
|
||||
|
||||
Explain the principles that guide the development of Docusaurus.
|
||||
|
||||
References
|
||||
---
|
||||
- https://www.gatsbyjs.org/docs/behind-the-scenes/
|
||||
- https://reactjs.org/docs/design-principles.html
|
||||
- https://v1.vuepress.vuejs.org/miscellaneous/design-concepts.html
|
||||
|
||||
-->
|
||||
|
||||
## Comparison with other tools {#comparison-with-other-tools}
|
||||
|
||||
Across all static site generators, Docusaurus has a unique focus on doc sites and has out-of-the-box structure you need.
|
||||
Across all static site generators, Docusaurus has a unique focus on documentation sites and has many out-of-the-box features.
|
||||
|
||||
We've also studied other main static site generators and would like to share our insights on the comparison, hopefully to help you navigate through the prismatic choices out there.
|
||||
|
||||
### Gatsby {#gatsby}
|
||||
|
||||
Gatsby is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
|
||||
[Gatsby](https://www.gatsbyjs.com/) is packed with a lot of features, has a rich ecosystem of plugins and is capable of doing everything that Docusaurus does. Naturally, that comes at a cost of a higher learning curve. Gatsby does many things well and is suitable for building many types of websites. On the other hand, Docusaurus tries to do one thing super well - be the best tool for writing and publishing content.
|
||||
|
||||
GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.
|
||||
|
||||
Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
|
||||
|
||||
[Dokz](https://github.com/pedronauck/docz) is a Gatsby theme to build documentation website. It is currently less featured than Docusaurus.
|
||||
|
||||
### Next.js {#nextjs}
|
||||
|
||||
[Next.js](https://nextjs.org/) is another very popular hybrid React framework. It can help you build a good documentation website, but it is not opinionated toward the documentation use-case, and it will require a lot more work to implement what Docusaurus provides out-of-the-box.
|
||||
|
||||
[Nextra](https://github.com/shuding/nextra) is an opinionated static-site-generator built on top of Next.js. It is currently less featured than Docusaurus.
|
||||
|
||||
### VuePress {#vuepress}
|
||||
|
||||
[VuePress](https://vuepress.vuejs.org/) has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.
|
||||
|
||||
### MkDocs {#mkdocs}
|
||||
|
||||
[MkDocs](https://www.mkdocs.org/) is a popular Python static-site-generator with value proposition similar to Docusaurus.
|
||||
|
||||
It is a good option if you don't need a single-page application, and don't plan to leverage React.
|
||||
|
||||
[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) is a beautiful theme.
|
||||
|
||||
### Docsify {#docsify}
|
||||
|
||||
[Docsify](https://docsify.js.org/) makes it easy to create a documentation website, but is not a static-site generator and is not SEO friendly.
|
||||
|
||||
### GitBook {#gitbook}
|
||||
|
||||
GitBook has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
|
||||
[GitBook](https://www.gitbook.com/) has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
|
||||
|
||||
Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
|
||||
|
||||
### Jekyll {#jekyll}
|
||||
|
||||
Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.
|
||||
[Jekyll](https://github.com/jekyll/jekyll) is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.
|
||||
|
||||
In comparison with statically generated HTML and interactivity added using `<script />` tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.
|
||||
|
||||
### VuePress {#vuepress}
|
||||
|
||||
VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.
|
||||
|
||||
<!-- TODO: Add a Next.js comparison -->
|
||||
|
||||
## Staying informed {#staying-informed}
|
||||
|
||||
- [GitHub](https://github.com/facebook/docusaurus)
|
||||
- [Twitter](https://twitter.com/docusaurus)
|
||||
- [Blog](/blog)
|
||||
- [Discord](https://discord.gg/Je6Ash6)
|
||||
|
||||
## Something missing? {#something-missing}
|
||||
|
||||
|
|
|
|||
|
|
@ -8,6 +8,16 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
|
|||
|
||||
We try to make this as easy as possible, and provide a migration cli.
|
||||
|
||||
## Main differences
|
||||
|
||||
Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser.
|
||||
|
||||
Docusaurus 2 is rebuilt it from the ground up, generates a single-page-application, using the full power of React in the browser. It allows for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n.
|
||||
|
||||
Beyond that, Docusaurus 2 is a **performant static site generator** and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.
|
||||
|
||||
While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.**
|
||||
|
||||
## Docusaurus 1 structure {#docusaurus-1-structure}
|
||||
|
||||
Your Docusaurus 1 site should have the following structure:
|
||||
|
|
|
|||
|
|
@ -100,7 +100,7 @@ Use this component to render React Context providers and global stateful logic.
|
|||
|
||||
:::caution
|
||||
|
||||
We would like to discourage swizzling of components until we've minimally reached a Beta stage. The components APIs have been changing rapidly and are likely to keep changing until we reach Beta. Stick with the default appearance for now if possible to save yourself some potential pain in future.
|
||||
We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now.
|
||||
|
||||
:::
|
||||
|
||||
|
|
|
|||
|
|
@ -81,6 +81,7 @@ const isVersioningDisabled = !!process.env.DISABLE_VERSIONING || isI18nStaging;
|
|||
{
|
||||
id: 'community',
|
||||
path: 'community',
|
||||
routeBasePath: 'community',
|
||||
editUrl: ({locale, versionDocsDirPath, docPath}) => {
|
||||
if (locale !== 'en') {
|
||||
return `https://crowdin.com/project/docusaurus-v2/${locale}`;
|
||||
|
|
@ -88,7 +89,6 @@ const isVersioningDisabled = !!process.env.DISABLE_VERSIONING || isI18nStaging;
|
|||
return `https://github.com/facebook/docusaurus/edit/master/website/${versionDocsDirPath}/${docPath}`;
|
||||
},
|
||||
editCurrentVersion: true,
|
||||
routeBasePath: 'community',
|
||||
sidebarPath: require.resolve('./sidebarsCommunity.js'),
|
||||
showLastUpdateAuthor: true,
|
||||
showLastUpdateTime: true,
|
||||
|
|
|
|||
|
|
@ -7,11 +7,7 @@
|
|||
|
||||
module.exports = {
|
||||
docs: [
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Docusaurus',
|
||||
items: ['introduction', 'design-principles', 'contributing'],
|
||||
},
|
||||
'introduction',
|
||||
{
|
||||
type: 'category',
|
||||
label: 'Getting Started',
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue