mirror of
https://github.com/facebook/docusaurus.git
synced 2025-06-01 18:32:52 +02:00
docs(v2): recommend Docusaurus 2 usage (#3785)
* recommend using Docusaurus v2 * Little improvements Co-authored-by: Alexey Pyltsyn <lex61rus@gmail.com>
This commit is contained in:
Sébastien Lorber
GitHub
parent
04f307cf66
commit
533bc6ad9a
6 changed files with 52 additions and 44 deletions
|
|
@ -64,14 +64,15 @@ class Index extends React.Component {
|
|||
<HomeSplash siteConfig={siteConfig} language={language} />
|
||||
<div className="announcement">
|
||||
<div className="announcement-inner">
|
||||
If you don't need advanced features such as versioning or
|
||||
translations, try out{' '}
|
||||
<a href="https://v2.docusaurus.io">Docusaurus 2</a> instead!
|
||||
Contribute to its roadmap by suggesting features or{' '}
|
||||
<a href="https://v2.docusaurus.io/feedback/">
|
||||
giving feedback here
|
||||
</a>
|
||||
!
|
||||
<div>
|
||||
<span className="announcement-important">IMPORTANT</span>: this is
|
||||
the documentation of{' '}
|
||||
<span className="announcement-important">Docusaurus v1</span>.
|
||||
</div>
|
||||
<div>
|
||||
We now recommend using{' '}
|
||||
<a href="https://v2.docusaurus.io">Docusaurus 2</a> instead!
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div className="mainContainer">
|
||||
|
|
|
|||
|
|
@ -73,6 +73,11 @@ table td:first-child > code {
|
|||
max-width: 768px;
|
||||
}
|
||||
|
||||
.announcement-important {
|
||||
color: #d00101;
|
||||
font-weight: bold;
|
||||
}
|
||||
|
||||
.index-hero {
|
||||
background-color: #2b3137;
|
||||
padding: 48px;
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
|
|||
|
||||
:::caution
|
||||
|
||||
This migration guide is targeted at Docusaurus users without translation and/or versioning features.
|
||||
For v1 translated sites, the migration doc is not available yet.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -725,12 +725,6 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch
|
|||
|
||||
## Versioned Site
|
||||
|
||||
:::caution
|
||||
|
||||
The versioning feature is a work in progress! Although we've implemented docs versioning since `2.0.0-alpha.37`, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work.
|
||||
|
||||
:::
|
||||
|
||||
Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
|
||||
|
||||
### Migrate your `versioned_docs` front matter
|
||||
|
|
@ -895,3 +889,9 @@ hello world
|
|||
- pre style="background: black">zzz</pre>
|
||||
+ pre style={{background: 'black'}}>zzz</pre>
|
||||
```
|
||||
|
||||
## Translated Site
|
||||
|
||||
We don't provide yet a migration path for v1 translated sites.
|
||||
|
||||
v2 i18n support is a [work in progress](https://github.com/facebook/docusaurus/pull/3325), and will be added before the end of 2020 with a migration guide to help you migrate from v1 + Crowdin to v2 + Crowdin.
|
||||
|
|
|
|||
|
|
@ -7,22 +7,23 @@ slug: /
|
|||
|
||||
## Disclaimer
|
||||
|
||||
It has been a year since we made the first **alpha release** of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:.
|
||||
Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable.
|
||||
|
||||
**You should use this if:**
|
||||
We highly encourage you to **use Docusaurus v2 over Docusaurus v1**.
|
||||
|
||||
- :white_check_mark: You want to contribute to Docusaurus 2
|
||||
- :white_check_mark: You want to build a modern website with client-side routing and prerendering
|
||||
- :white_check_mark: You want to provide feedback to make sure Docusaurus 2 suits your needs
|
||||
- :white_check_mark: You are curious about what comes next as a Docusaurus user
|
||||
- :white_check_mark: You want to ease the pain of migration in future
|
||||
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).
|
||||
|
||||
**Use **Docusaurus v2** if:**
|
||||
|
||||
- :white_check_mark: You want a modern Jamstack documentation site
|
||||
- :white_check_mark: You want a single-page application (SPA) with client-side routing
|
||||
- :white_check_mark: You want the full power of React and MDX
|
||||
- :white_check_mark: You do not need support for IE11
|
||||
|
||||
**Do not use this if:**
|
||||
**Use [Docusaurus v1](https://docusaurus.io/) if:**
|
||||
|
||||
- :x: You need a fully production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead)
|
||||
- :x: You need the translation features present in v1
|
||||
- :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during the alpha period
|
||||
- :x: You don't want a single-page application (SPA)
|
||||
- :x: You prefer stability over modernity (try [Docusaurus 1](https://docusaurus.io/) instead)
|
||||
- :x: You need support for IE11
|
||||
|
||||
## A better Docusaurus is coming to town
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
|
|||
|
||||
:::caution
|
||||
|
||||
This migration guide is targeted at Docusaurus users without translation and/or versioning features.
|
||||
For v1 translated sites, the migration doc is not available yet.
|
||||
|
||||
:::
|
||||
|
||||
|
|
@ -725,12 +725,6 @@ For any questions, you can ask in the [`#docusaurus-1-to-2-migration` Discord ch
|
|||
|
||||
## Versioned Site
|
||||
|
||||
:::caution
|
||||
|
||||
The versioning feature is a work in progress! Although we've implemented docs versioning since `2.0.0-alpha.37`, we'd like to test it out for v2 users first before we recommend v1 users to migrate to v2. There are some changes in how v2 versioning works compared to v1. In the future, we might create a script to migrate your versioned docs easier. However, if you are adventurous enough to manually migrate, feel free to do so. Be warned though, the manual migration requires lot of work.
|
||||
|
||||
:::
|
||||
|
||||
Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
|
||||
|
||||
### Migrate your `versioned_docs` front matter
|
||||
|
|
@ -895,3 +889,9 @@ hello world
|
|||
- pre style="background: black">zzz</pre>
|
||||
+ pre style={{background: 'black'}}>zzz</pre>
|
||||
```
|
||||
|
||||
## Translated Site
|
||||
|
||||
We don't provide yet a migration path for v1 translated sites.
|
||||
|
||||
v2 i18n support is a [work in progress](https://github.com/facebook/docusaurus/pull/3325), and will be added before the end of 2020 with a migration guide to help you migrate from v1 + Crowdin to v2 + Crowdin.
|
||||
|
|
|
|||
|
|
@ -7,22 +7,23 @@ slug: /
|
|||
|
||||
## Disclaimer
|
||||
|
||||
It has been a year since we made the first **alpha release** of Docusaurus 2 and things have been pretty stable since then. Many of Facebook's new open source websites are using Docusaurus 2 now. At this point, we highly encourage you to use Docusaurus 2 over Docusaurus 1 for your new websites. For feedback and questions, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:.
|
||||
Docusaurus v2 is **still alpha** (since mid-2019) but already quite stable.
|
||||
|
||||
**You should use this if:**
|
||||
We highly encourage you to **use Docusaurus v2 over Docusaurus v1**.
|
||||
|
||||
- :white_check_mark: You want to contribute to Docusaurus 2
|
||||
- :white_check_mark: You want to build a modern website with client-side routing and prerendering
|
||||
- :white_check_mark: You want to provide feedback to make sure Docusaurus 2 suits your needs
|
||||
- :white_check_mark: You are curious about what comes next as a Docusaurus user
|
||||
- :white_check_mark: You want to ease the pain of migration in future
|
||||
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).
|
||||
|
||||
**Use **Docusaurus v2** if:**
|
||||
|
||||
- :white_check_mark: You want a modern Jamstack documentation site
|
||||
- :white_check_mark: You want a single-page application (SPA) with client-side routing
|
||||
- :white_check_mark: You want the full power of React and MDX
|
||||
- :white_check_mark: You do not need support for IE11
|
||||
|
||||
**Do not use this if:**
|
||||
**Use [Docusaurus v1](https://docusaurus.io/) if:**
|
||||
|
||||
- :x: You need a fully production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead)
|
||||
- :x: You need the translation features present in v1
|
||||
- :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during the alpha period
|
||||
- :x: You don't want a single-page application (SPA)
|
||||
- :x: You prefer stability over modernity (try [Docusaurus 1](https://docusaurus.io/) instead)
|
||||
- :x: You need support for IE11
|
||||
|
||||
## A better Docusaurus is coming to town
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue