3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-07-31 07:18:59 +02:00
Code Issues Projects Releases Packages Wiki Activity

chore: removal of Docusaurus v1 code from master (it is now available on docusaurus-v1 branch) (#4902)

Browse source
This commit is contained in:
Sébastien Lorber 2021-06-10 10:54:07 +02:00 • committed by GitHub
parent df8a900f9c
commit b835aecaec
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
463 changed files with 6 additions and 36940 deletions
Download patch file Download diff file Expand all files Collapse all files

160
website/blog/2017-12-14-introducing-docusaurus.md Normal file
View file

@ -0,0 +1,160 @@
---
title: Introducing Docusaurus
author: Joel Marcey
authorURL: http://twitter.com/JoelMarcey
authorImageURL: https://graph.facebook.com/611217057/picture/?height=200&width=200
authorFBID: 611217057
authorTwitter: JoelMarcey
tags: [documentation, blog, docusaurus]
---
![Introducing Slash](/img/slash-introducing.svg)
We are very happy to introduce [Docusaurus](https://github.com/facebook/docusaurus) to help you manage one or many open source websites.
We created [Docusaurus](https://docusaurus.io) for the following reasons:
1. To put the focus on writing good documentation instead of worrying about the infrastructure of a website.
1. To provide features that many of our open source websites need like blog support, search and versioning.
1. To make it easy to push updates, new features, and bug fixes to everyone all at once.
1. And, finally, to provide a consistent look and feel across all of our open source projects.
<!--truncate-->
Docusaurus is a tool designed to make it easy for teams to publish documentation websites without having to worry about the infrastructure and design details. At its core, all a user has to provide are documentation files written in markdown, customization of a provided home page written in React, and a few configuration modifications. Docusaurus handles the rest by providing default styles, site formatting, and simple document navigation. Getting started is easy, as users can [install](https://v1.docusaurus.io/docs/en/installation.html) it using `npm` or `yarn` via a simple initialization script that [creates a working example website out of the box](https://v1.docusaurus.io/docs/en/site-preparation.html).
Docusaurus also provides core website and documentation features out-of-the-box including [blog support](https://v1.docusaurus.io/docs/en/blog.html), [internationalization](https://v1.docusaurus.io/docs/en/translation.html), [search](https://v1.docusaurus.io/docs/en/search.html), and [versioning](https://v1.docusaurus.io/docs/en/versioning.html). While some projects may not require any of these features, enabling them is generally a matter of updating configuration options instead of having to add the infrastructure from the ground up. As more features get added to Docusaurus, users just can easily update to the latest version. This can be done by simply running npm or yarn update and updating configuration options. Users or teams will no longer need to manually rework their entire website infrastructure each time a new feature gets added.
## The Birth of docusaurus
![Birth of Slash](/img/slash-birth.png)
When Facebook first started their open source program, many teams implemented a custom website for each of their open source projects. This approach presented challenges when the open source program team was asked to help the project teams improve their documentation. Since each site was unique, adding basic infrastructure such as a blog, consistent navigation, search, etc. became challenging undertakings.
The open source team tried to help mitigate this problem by coming up with a standard template, based on Jekyll, that could be used as a starting point for a project website. We asked our new projects to manually copy our template source to their repo, write their docs, and publish. This template approach was adopted by most of open source projects launched; some existing projects even converted their custom website implementations to the new template as well.
The problem with the "copy the template to your repo" approach is that, even though the platform is consistent, pushing updates becomes unmaintainable across an entire suite of projects already using the template. This is because we lost control of the template after a project copied it to their repo. Projects were free to modify the template as desired and apply their own project-specific features to it. So while projects share the same site generation platform, they have now diverted enough where they cannot take advantage of the new features we have added to the template over time. There was no easy way we could ask all current projects to "copy" a new version of the template since it might break their existing site or remove features that they have added on their own. Instead, we would have to apply the updates manually to each project one-by-one. This became very problematic when projects started asking for our team for internationalization support within the template, requiring low-level changes to how the template was structured and generated.
So we started thinking about what we could do to help mitigate the challenge of keeping sites updated and consistent across our entire portfolio. We also wanted multiple projects to share the same site generation software. We wanted them to start out with the same template, and yet have the flexibility to customize and adapt their site theme to suit their needs. They should be able to extend and customize their site, but when we update the underlying infrastructure with fixes and features, the project should be able update simply and without any breaking changes.
Docusaurus was born!
At Facebook, Docusaurus allows us to quickly get different projects up and running with documentation websites, especially for teams who don't have much experience with web development or primarily want a basic site to showcase their project. Docusaurus already supports sites needing more advanced features like internationalization for Jest and versioning for React Native. As different projects request new features for their sites, they are added to Docusaurus and simultaneously provided to all projects! All together, this ends up greatly reducing the work needed to maintain different sites for different projects. Our teams are able to focus on keeping their projects healthier by spending more time adding features, fixing bugs, and writing documentation.
## Getting Up and Running
![Slash Up and Running](/img/slash-upandrunning.png)
At its core, we wanted sites running Docusaurus to be simple to use. With one [installation](https://v1.docusaurus.io/docs/en/installation.html) command and some simple [configuration](https://v1.docusaurus.io/docs/en/site-preparation.html), you can actually have a default running website.
When you run `docusaurus-init`, you will see a structure similar to:
```bash
root-of-repo
├── docs-examples-from-docusaurus
│ ├── doc1.md
│ ├── doc2.md
│ ├── doc3.md
│ ├── exampledoc4.md
│ └── exampledoc5.md
├── website
│ ├── blog-examples-from-docusaurus
│ │ ├── 2016-03-11-blog-post.md
│ │ └── 2017-04-10-blog-post-two.md
│ ├── core
│ │ └── Footer.js
│ ├── node_modules
│ ├── package.json
│ ├── pages
│ ├── sidebars.json
│ ├── siteConfig.js
│ └── static
```
With the exception of node_modules and package.json, all the directories and files you see are where you customize and add content to your Docusaurus-based website. The docs folder is where you add your markdown that represents your documentation; the blog folder is where you add your markdown for your [blog posts](https://v1.docusaurus.io/docs/en/blog.html); `siteConfig.js` is where you make most of the [customizations](https://v1.docusaurus.io/docs/en/site-config.html) for your site; `sidebars.json` is where you maintain the layout and content of the [sidebar](https://v1.docusaurus.io/docs/en/navigation.html) for your documentation; the `pages` folder is where you add [custom](https://v1.docusaurus.io/docs/en/custom-pages.html) pages for your site; the `static` folder is where all of your static assets go (e.g., CSS stylesheets and images); and the `core` folder is where you can customize core components of the site, in this case the footer.
## How does Docusaurus work?
Docusaurus is written primarily in JavaScript and [React](https://facebook.github.io/react), replacing Jekyll which we used in the old template. We use [Remarkable](https://github.com/jonschlinkert/remarkable) for our markdown rendering and [highlight.js](https://highlightjs.org/) for our code block syntax highlighting. The core of Docusaurus' functionality is in the [lib directory](https://github.com/facebookexperimental/Docusaurus/tree/master/lib) of the [Docusaurus repo](https://github.com/facebook/docusaurus/). The general structure looks like:
```bash
root-of-Docusaurus
├── lib
│ ├── core
│ ├── server
│ │ ├── generate.js
│ │ ├── server.js
│ │ └── ...and more files
│ ├── static
│ ├── build-files.js
│ ├── copy-examples.js
│ ├── generate-feed.js
│ ├── publish-gh-pages.js
│ ├── rename-version.js
│ ├── start-server.js
│ ├── versions.js
│ └── write-translations.js
```
The key files here are build-files.js and start-server.js. There are many similarities between these two files: `build-files.js` is used to build the physical artifacts for serving by an external web server. `start-server.js` is used to run the Docusaurus server and locally test your site. Both go through the following general process to take all of the markdown and configuration to create a runnable website:
1. Process your website settings in `siteConfig.js`
1. Read the document metadata that exists in all the markdown files in your docs directory.
1. Create a table of contents for your documents based upon the ids extracted from the metadata.
1. Convert the markdown to HTML, including doing link replacement.
1. These files will go in a build/docs directory of the compiled site, and any translated versions will go into a language specific folder within the build/docs folder.
1. Repeat 1-3 for blog posts.
1. The blog file will go in a build/blog directory of the compiled site.
1. Read the main.css file and concatenate any user-defined css into master css file that will be in the build/css directory of the compiled site.
1. Copy images into an build/img directory of the compiled site.
1. Take any custom pages that were added to the pages folder of the site and compile/copy those into the root build directory of the compiled site. Any translated versions will go into a language specific folder within build.
1. Create CNAME and sitemap.xml files and add those to build.
Note that this process does not take into full account how translations or versioning works. The underlying details of those features will be saved for future blog posts.
The final structure of your compiled site will look similar to:
```bash
build
├── website
│ ├── CNAME
│ ├── blog
│ ├── css
│ ├── docs
│ ├── en
│ ├── help.html # custom page
│ ├── img
│ ├── index.html # landing page
│ ├── sitemap.xml
│ └── users.html # custom page
```
## Community
![Docusaurus](/img/docusaurus.svg)
We welcome your [contributions](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to Docusaurus, whether you want to use it for your own site, you want to [contribute](https://github.com/facebook/docusaurus/blob/master/CONTRIBUTING.md) to the Docusaurus core or just have questions. Follow us on [GitHub](https://github.com/facebook/docusaurus) and [Twitter](https://twitter.com/docusaurus).
## Acknowledgements
Docusaurus wouldn't exist without the work of the rest of the core Docusaurus team: [Eric Nakagawa](http://twitter.com/ericnakagawa), [Hector Ramos](https://twitter.com/hectorramos), [Eric Vicenti](https://twitter.com/EricVicenti) and [Frank Li](https://github.com/deltice) — a former intern at Facebook who implemented the core technology and features.
Special thanks also goes out to our earliest [adopters](https://v1.docusaurus.io/en/users.html) of Docusaurus:
- [BuckleScript](https://bucklescript.github.io/)
- [FastText](https://fasttext.cc)
- [Jest](https://jestjs.io)
- [Make It Open](http://makeitopen.com)
- [Prettier](https://prettier.io/)
- [Reason-react](https://reasonml.github.io/reason-react/)
- [React Native](https://facebook.github.io/react-native/)
- [Relay](https://facebook.github.io/relay/)
Without their dedication to creating or migrating their websites over to the platform, we would have not have been in the position where we are today.
## Resources
- [Read our documentation](https://v1.docusaurus.io)
- [Follow our Twitter feed](https://twitter.com/docusaurus)
- [Follow us on GitHub](https://github.com/facebook/docusaurus)
- [About Slash, the Docusaurus mascot](https://v1.docusaurus.io/about-slash.html)

122
website/blog/2018-04-30-How-I-Converted-Profilo-To-Docusaurus.md Normal file
View file

@ -0,0 +1,122 @@
---
title: How I Converted Profilo to Docusaurus in Under 2 Hours
author: Christine Abernathy
authorURL: http://twitter.com/abernathyca
authorImageURL: https://graph.facebook.com/1424840234/picture/?height=200&width=200
authorFBID: 1424840234
authorTwitter: abernathyca
tags: [profilo, adoption]
---
> _“Joel and I were discussing having a website and how it would have been great to launch with it. So I challenged myself to add Docusaurus support. It took just over an hour and a half. I'm going to send you a PR with the addition so you can take a look and see if you like it. Your workflow for adding docs wouldn't be much different from editing those markdown files.”_
>
> _— Note sent to the Profilo team_
This is the story of the rather short journey it took to create the [Profilo](https://facebookincubator.github.io/profilo/) website using Docusaurus.
Profilo, an Android library for collecting performance traces from production, [was announced](https://code.fb.com/android/profilo-understanding-app-performance-in-the-wild/) earlier this year. The project was [published on GitHub](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8) with a less than [a handful or Markdown files](https://github.com/facebookincubator/profilo/tree/802042f90f990998a272387e371b893af52465b8/docs) to describe its functionality and no website to showcase any branding and highlight the logo. The task at hand was to turn these existing docs and logo into a website.
<!--truncate-->
In general, when creating a website with Docusaurus you do the following:
1. Generate a template website using Docusaurus scripts.
1. Customize the generated template files for your desired site colors and your project configuration (ex: website and GitHub links).
1. Create the website content:
1. Add your docs and any supporting assets.
1. Customize the default landing page provided by Docusaurus to suit your needs.
1. Configure the default site navigation file.
1. Publish the website and set up how it will be published for future changes.
Given I had pre-existing Markdown files, I didn't have to generate the core content but simply make sure that Docusaurus could process the files by adding the expected metadata to them. Most of the work would therefore consist of customizing the defaults provided by Docusaurus.
## Overview of Steps Taken
Here's an overview of the steps taken to convert to a website. I'll discuss some of the design aspects in a later section.
**Design and colors:**
1. Got all the desired logo formats from designer. I had to create the _.favicon_ one.
1. Worked out some passable primary and secondary website colors using the http://paletton.com/ tools - very handy!
**Initial website setup:**
1. Forked the [Profilo project](https://github.com/facebookincubator/profilo/) on GitHub and created a local clone of the fork to set up the website.
1. Created the initial Docusaurus website using the [installation instructions](https://v1.docusaurus.io/docs/en/installation.html).
1. Deleted the `docs-examples-from-docusaurus` and `website/blog-examples-from-docusaurus` folders as these would not be needed. Profilo had existing docs we could use and there was no need for blogs at this time.
**Content creation:**
1. Added metadata to the existing Markdown files found in the `docs` folder, for example:
+---
+id: architecture
+title: Architecture
+sidebar_label: Architecture
+---
1. Added the logo assets to the `website/static/img` folder.
1. Modified `website/pages/en/index.js`, the landing page, to highlight Profilo features.
1. Modified `website/core/Footer.js`, the footer, to simplify it for Profilo.
1. Edited `website/siteConfig.js` (website configuration file) to specify the previously chosen primary and secondary colors.
1. Modified `website/sidebars.json` that specifies the sidebar navigation. Listed all the docs and customized it based on the metadata added to the Markdown files.
1. Edited the website configuration file to specify the GitHub properties, logo images, header links, and the website link.
1. Tested the website locally throughout this phase. (I ran `yarn start` from the `website` folder to start the server.)
**Feedback and review changes:**
1. Sent a [pull request](https://github.com/facebookincubator/profilo/pull/6) to the project.
1. Updated the colors after the designer rightly gasped at the ones I had chosen (IANAD).
1. Updated the colors and updated the PR.
1. The PR was then accepted and [merged](https://github.com/facebookincubator/profilo/commit/6ad033aaf5a7d54e6d842f45a5bccd051a8e45ad). Yay!
**Website publishing:**
1. Pushed the first website version by running the Docusaurus publish script from the command line:
USE_SSH=true \
GIT_USER=caabernathy \
CURRENT_BRANCH=master \
yarn run publish-gh-pages
1. Configured CircleCI using the [provided Docusaurus instructions](https://v1.docusaurus.io/docs/en/publishing.html#automating-deployments-using-continuous-integration). There were 2 PRs for this, [the first](https://github.com/facebookincubator/profilo/pull/8)for the initial config and [the second](https://github.com/facebookincubator/profilo/pull/12) to make sure CircleCI only triggered for changes in the master branch (thanks Joel Marcey!).
The final website was published on https://facebookincubator.github.io/profilo/. It had taken 1.5 hours to get to the initial PR stage and another half an hour or so to respond to review feedback and publish the website.
## Design
Here's what the initial website looked like when the first pull request was sent out:
![Website Initial Design](/img/profilo_blog_post_website_initial.png)
Most of the time in the content creation was spent picking colors that worked reasonably well with the given logo. These colors were a good jumping off point for designer feedback. I used Photoshop to sample various portions of the logo.
![Picking Color Photoshop](/img/profilo_blog_post_photoshop_color_picker.png)
I then took the RGB representation of the color and set it as the baseline color on [Paletton](http://paletton.com/). The website then gave me various color options to try on the website by editing the Docusaurus website configuration file.
![Picking Color Paletton](/img/profilo_blog_post_palette_website_color_picker.png)
The selected primary and secondary colors were a good jumping off point for designer feedback.
There were also modifications made to the default website generated by Docusaurus. These changes were mainly around simplifying the footer and creating a customized landing page for Profilo that listed the project's features.
Here's what the final website looked like:
![Website Final Design](/img/profilo_blog_post_website_final.png)
This is an example page showing the core content, in this case the Getting Started page:
![Website Docs Example](/img/profilo_blog_post_website_final_docs.png)
This also shows the sidebar structure that was set up through editing `website/sidebars.json`.
Lastly, I didn't have to worry about handling responsive design. You get this out of the box with Docusaurus!
![Mobile Site](/img/profilo_blog_post_android_ios.png)
## Final Thoughts
The Profilo engineers were happy to see that they didn't have to change their workflow to update existing content. They were able to continue working with Markdown files. This will still be true in the future if new docs are added, although there may be some config changes needed if the sidebar navigation needs to be updated.
The infrastructure provided by Docusaurus made it easy to convert Markdown files into a working website. Even though the project had only three docs, this gave Profilo a more professional look. So, it was well worth the short time investment to get it done.

134
website/blog/2018-09-11-Towards-Docusaurus-2.md Normal file
View file

@ -0,0 +1,134 @@
---
title: Towards Docusaurus 2
author: Endilie Yacop Sucipto
authorTitle: Maintainer of Docusaurus
authorURL: https://github.com/endiliey
authorImageURL: https://avatars1.githubusercontent.com/u/17883920?s=460&v=4
authorTwitter: endiliey
tags: [new, adoption]
---
Docusaurus was [officially announced](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus) over nine months ago as a way to easily build open source documentation websites. Since then, it has amassed over 8,600 GitHub Stars, and is used by many popular open source projects such as [React Native](https://facebook.github.io/react-native/), [Babel](https://babeljs.io/), [Jest](https://jestjs.io/), [Reason](https://reasonml.github.io/) and [Prettier](https://prettier.io/).
There is a saying that the very best software is constantly evolving, and the very worst is not. In case you are not aware, we have been planning and working on the next version of Docusaurus 🎉.
<!--truncate-->
## Introduction
It all started with this [RFC issue](https://github.com/facebook/docusaurus/issues/789) opened by [Yangshun](https://github.com/yangshun) towards the end of June 2018.
<blockquote><h4><a href="https://github.com/facebook/docusaurus/issues/789">[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus</a></h4><p>These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. A number of the ideas here were inspired by VuePress and other static site generators. In the current static site generators ecosystem, t...</p></blockquote>
Most of the suggested improvements are mentioned in the issue; I will provide details on some of issues in Docusaurus 1 and how we are going to address them in Docusaurus 2.
## Infrastructure
### Content
A Docusaurus 1 website is, in fact, built into a bunch of static HTML pages. Despite using React, we were not fully utilizing the features React offered, such as component state, which allows for dynamic and interactive pages. React was only used as a templating engine for static content and interactivity has to be added through script tags and `dangerouslySetInnerHTML` 😱.
In addition, there is not an easy way to change how Docusaurus loads content. For example, adding CSS preprocessors such as Sass and Less was not supported natively and involved many user hacks of adding custom scripts.
For Docusaurus 2, we will be using [webpack](https://webpack.js.org/) as a module bundler and we are changing the way we serve content. Adding CSS preprocessors will be as easy as adding a webpack loader. Instead of a pure static HTML, **during build time we will create a server-rendered version of the app** and render the corresponding HTML. A Docusaurus site will be essentially an isomorphic/universal application. This approach is heavily inspired by [Gatsby](https://github.com/gatsbyjs/gatsby).
### Versioning
If you have been using Docusaurus for a while, you might notice that Docusaurus creates versioned docs **if and only if** the docs content are **different**.
For example, if we have `docs/hello.md`:
```text
---
id: hello
title: hello
---
Hello world !
```
And **we cut version 1.0.0,** Docusaurus will create `versioned_docs/version-1.0.0/hello.md`:
```text
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
```
However, if there are no changes to `hello.md` when cutting v2.0.0, Docusaurus will not create any versioned docs for that document. In other words, `versioned_docs/version-2.0.0/hello.md` will not exist.
This can be very confusing for users; if they want to edit the v2.0.0 docs, they have to edit `versioned_docs/version-1.0.0/hello.md` or manually add `versioned_docs/version-2.0.0/hello.md`. This could potentially lead to unwanted bugs. Here is a [real scenario in Jest](https://github.com/facebook/jest/pull/6758#issuecomment-408274413).
In addition, this adds complexity within the codebase as we require a mechanism for version fallbacks. And during build time, Docusaurus has to replace the linking to the correct version. This is also the cause of a bug where [renaming docs breaks links in old versions](https://github.com/facebook/docusaurus/issues/845).
For Docusaurus 2, **every time we cut a new version, we will instead take a snapshot of all the docs**. We will not require the content of a document to have changed. This is a space complexity trade-off for a better developer and user experience. We will use more space for better separation of concerns and guaranteed correctness.
### Translation
Docusaurus allows for easy translation functionality by using [Crowdin](https://crowdin.com/). Documentation files written in English are uploaded to Crowdin for translation by users within a community. We always assumed that **English** is the default language, but this might not be the case for all users. We have seen plenty of non-English open source projects using Docusaurus.
For Docusaurus 2, **we will not assume English is the default language**. When a user enables internationalization, they have to set a default language in `siteConfig.js`. We will then assume that all the files in `docs` are written in that language.
In addition, after working on the MVP of Docusaurus 2, I realized that it is possible not to use Crowdin for translations. Thus, we might need to add an additional workflow to enable that scenario. However, we will still strongly recommend people use Crowdin for easier integration.
## Customizability
### Layout
The current state of Docusaurus is that it is in charge of the entire layout and styling, unintentionally making it very hard for users to customize their site's appearance to their wishes.
For Docusaurus 2, **layout and styling should be controlled by the user**. Docusaurus will handle the content generation, routing, translation, and versioning. Inspired by [create-react-app](https://github.com/facebook/create-react-app) and [VuePress](https://vuepress.vuejs.org/), Docusaurus will still provide a default theme, which the user can eject from, for further layout and styling customization. This means that it is very possible for the user to even change the HTML meta by using [React Helmet](https://github.com/nfl/react-helmet). Community-based themes are also very possible. This approach of allowing users to be in charge of layout and styling is taken by most static site generators.
### Markdown
Our markdown parsing is currently powered by [Remarkable](https://github.com/jonschlinkert/remarkable). What if the user wants to use [markdown-it](https://github.com/markdown-it/markdown-it) or even [MDX](https://github.com/mdx-js/mdx)? And then there is an issue of which syntax highlighter to use, (e.g: [Prism](https://prismjs.com/) vs [Highlight.js](https://highlightjs.org/)). We should leave these choices open to the user.
For Docusaurus 2, **users can eject and choose their own markdown parser**. It does not matter if they want to use another markdown parser such as [Remark](https://github.com/remarkjs/remark), or even their own in-house markdown parser. As a rule of thumb, the user has to provide a React component, in which we will provide a children props containing the _RAW string of markdown_. By default, we will use Remarkable for the markdown parser and Highlight.js for the syntax highlighting. The default parser could still change in the future as we're still experimenting with different markdown parsers.
### Search
Our core search functionality is based on [Algolia](https://www.algolia.com/). There are requests by users to be able to use different search offerings, such as `lunrjs` for offline search.
I personally like Algolia and we have a great experience working with them. They are very responsive; we can easily submit a pull request to Algolia since their `DocSearch` is open source. For example, I recently submitted [this PR that enables DocSearch to scrape alternate languages in sitemap](https://github.com/algolia/docsearch-scraper/pull/387).
For Docusaurus 2, **we will allow users to customize the search box**. Users simply need to eject from the default theme and modify the Search UI (a React component). However, we will still use Algolia in the default theme.
## Stability
Software is never going to be perfect, but we want Docusaurus to not break as we add new features. When Docusaurus was first released, it did not have any strong automated test suites. As a result, there were a lot of regressions not caught early. Although we have recently added a lot of tests, the test coverage is still relatively low.
For Docusaurus 2, **we are adding tests as we develop** since we are going for a fresh rewrite. Hence, I believe that it should be more stable than ever and it should be harder to break things compared to Docusaurus 1.
## Frequently Asked Questions
### Will there be any breaking changes?
If you've read the post up until to this point, you should be able to notice that there will be breaking changes. While we will try to **minimize the number of breaking changes** and make it backward compatible as much as possible, we believe that some breaking changes are required. This is mostly due to Docusaurus 2 being a **major rewrite and re-architecting** of the codebase.
The exact list of breaking changes is not totally known yet as development is not 100% finalized. However, one thing that I will highlight is that we will deprecate a lot of options in `siteConfig.js` and we plan to keep it as lean as possible. For example, the `cleanUrl` siteConfig will be deprecated as all the URL for Docusaurus 2 sites will be without the `.html` suffix.
Our goal is that most sites should be able to upgrade to Docusaurus 2 without a lot of pain. We will also include a migration guide when we release Docusaurus 2. When the times come, feel free to ping us on [Discord](https://discord.gg/docusaurus) or [Twitter](https://twitter.com/docusaurus) for questions and help.
### When is the release of Docusaurus 2?
As of now, we do not have an exact date planned for the release. I personally estimate that we might be able to release an alpha version in the next one to two months, but this is, of course, just an estimate.
One thing that I would like to share is that while Docusaurus is part of [Facebook Open Source](https://opensource.fb.com/) and most of the team are Facebook employees, the maintenance and development work is mostly done outside of normal working hours. I am currently a final year undergraduate student at [NTU Singapore](https://twitter.com/NTUsg), so I had to juggle between doing my coursework, my final year project and maintaining/developing Docusaurus. However, that does not mean that we do not want to make Docusaurus better. In fact, **we want to make it as awesome as possible**.
For now, the actual Docusaurus 2 work is still hosted in a private repository. In the near future, we will move them into the [public repository](https://github.com/facebook/docusaurus). When that time arrives, I encourage everyone to look into it and hopefully contribute in some way. Before then, please stay tuned 😉!
## Final Thoughts
Docusaurus has had a large impact on the open source community as seen from the [many popular projects](https://v1.docusaurus.io/en/users) which use Docusaurus for documentation. In order to move faster in the future, we are taking the opportunity to fix some core problems with Docusaurus 1 and striving to make Docusaurus better for everyone. In fact, it is safe to say that Docusaurus 2 is not just a plan any longer; the work on it has started and, hopefully, we will be able to see it materialize in the near future.
Docusaurus' mission has always been to make it really easy for you to get a website with documentation up and running out of the box. That mission does not change with Docusaurus 2.
We also want to let people know that **due to work on Docusaurus 2, we will be less likely to accept new features/major changes on Docusaurus 1.**
If you are using Docusaurus, you are part of our community; keep letting us know how we can make Docusaurus better for you. If you appreciate the work we're doing, you can support [Docusaurus on Open Collective](https://opencollective.com/Docusaurus).
> If you are sponsoring our work on [Open Collective](https://opencollective.com/Docusaurus), we'll personally offer you a helping hand for maintenance and upgrading of Docusaurus website.
Lastly, if you haven't done so already, click the **star** and **watch** button on [GitHub](https://github.com/facebook/docusaurus), and follow us on [Twitter](https://twitter.com/docusaurus).

22
website/blog/2018-12-14-Happy-First-Birthday-Slash.md Normal file
View file

@ -0,0 +1,22 @@
---
title: Happy 1st Birthday Slash!
author: Joel Marcey
authorTitle: Co-creator of Docusaurus
authorURL: https://github.com/JoelMarcey
authorImageURL: https://graph.facebook.com/611217057/picture/?height=200&width=200
authorFBID: 611217057
authorTwitter: JoelMarcey
tags: [birth]
---
![First Birthday Slash](/img/docusaurus-slash-first-birthday.svg)
Docusaurus [went live](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus) on December 14, 2017. At the time, we had [8 early adopters](https://v1.docusaurus.io/blog/2017/12/14/introducing-docusaurus#acknowledgements).
<!--truncate-->
We now have nearly [60 known users of Docusaurus](https://v1.docusaurus.io/en/users), and probably more that we don't know about. We have [9K GitHub stars](https://github.com/facebook/docusaurus) and an active community, particularly [Yangshun Tay](https://twitter.com/yangshunz) and [Endilie Yacop Sucipto](https://twitter.com/endiliey), both of whom are the lead maintainers helping keep this project [moving forward](https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2).
Thank you to everyone for your support and use of this project! I am super proud of how far this project has come in just a year.
> Special thanks to [Eric Nakagawa](https://twitter.com/ericnakagawa), creator of Slash, for creating this 1-year image of Slash enjoying cake. The Slash brand has been a boon for us!

65
website/blog/2019-12-30-docusaurus-2019-recap.md Normal file
View file

@ -0,0 +1,65 @@
---
title: Docusaurus 2019 Recap
author: Yangshun Tay
authorTitle: Front End Engineer at Facebook
authorURL: https://github.com/yangshun
authorImageURL: https://avatars1.githubusercontent.com/u/1315101?s=460&v=4
authorTwitter: yangshunz
tags: [recap]
---
2019 was a great year for Docusaurus - we've made tremendous progress on [Docusaurus 2](https://docusaurus.io/). Current Docusaurus 1 users who aren't using the translations feature can feel free to check it out and [migrate](https://docusaurus.io/docs/migration) to it! Otherwise we will work with you to make that happen in 2020 :)
<!--truncate-->
## Docusaurus 2 (D2)
In 2018, we proposed to rebuild [Docusaurus from the ground up](https://github.com/facebook/docusaurus/issues/789). It involved a major rearchitecture effort - we created a content-centric CSS framework from scratch, a plugins system, and moved from static HTML pages to be a single page-app with prerendered routes. It was a wild adventure and a tough feat, especially with no dedicated FTE working on the project. With the help of [@endilie](https://github.com/endiliey), our ex-intern-turned-contributor-turned-maintainer, we made really good progress on D2 and are currently on version 2.0.0-alpha.40. All features in Docusaurus 1 except for translations have been ported over.
D2's killer features are **Dark Mode** and its **superb performance**. D2 has dark mode support out-of-the-box and it is near effortless to create a dark mode-friendly documentation site. Endilie put in great effort into optimizing the performance of the site and a bunch of performance optimization tricks have been done under the hood by default - optimized images, prerendering every route to static HTML and client-side routing thereafter, prefetching assets needed by future navigations whenever the user hovers over a navigation link, etc.
Last but not least, we implemented a plugins architecture and turned the repo into a [Lerna monorepo](https://github.com/facebook/docusaurus/tree/master/packages). We believe this plugin architecture will be helpful towards building a community and also allowing users to build their own features for their unique use cases.
## GitHub Activity
- Stars: 10050 -> 14632 (+45.6% y/y)
- Total Contributors: 182 -> 303 (+66.4% y/y). Most of which are non-Facebook contributors
- Daily npm Downloads: 728 -> 2320 (+218.7% y/y). The peak was in November
- D1 is currently used by 3872 projects on GitHub while D2 is used by 247 projects on GitHub
- We now have 4 active core contributors! (+100% y/y)
## Notable Users
A good portion of the projects within the Open Source community use Docusaurus. This half we also onboarded more notable projects onto Docusaurus 2:
- [Create React App](https://create-react-app.dev/)
- [Redux](https://redux.js.org/)
- [Draft.js](https://draftjs.org/)
- [Flux](http://facebook.github.io/flux/)
And welcomed more projects to Docusaurus 1:
- [Libra](https://developers.libra.org/)
- [MobX](https://mobx.js.org/)
- [Immer](https://immerjs.github.io/immer/)
- [Sorbet](https://sorbet.org/)
## Media
Yangshun gave a classroom session during F8 about [Using Docusaurus to Create Open Source Websites](https://www.youtube.com/watch?v=QcGJsf6mgZE).
## Community
A few third-party hosting/development services also has first-class integration with a Docusaurus setup:
- [ZEIT Now deployment](https://github.com/zeit/now-examples/tree/master/docusaurus)
- [CodeSandbox](https://codesandbox.io/s/docusaurus-template-x3vg9)
- [Render](https://render.com/docs/deploy-docusaurus)
## Looking Ahead
D2 has gained some traction among the [developer community](https://docusaurus.io/showcase). In 2020, we want to achieve full feature parity with D1 by the first half and help the remaining Facebook projects on D1 move to D2. It would also be great if we could use Docusaurus for internal documentation, but that is a non-trivial undertaking. If you have a need for it or have some ideas, come speak with us!
Huge thanks to the community for their contributions, especially the core team - [Endilie Yacop Sucipto](https://github.com/endiliey), [Alexey Pyltsyn](https://github.com/lex111), [Wei Gao](https://github.com/wgao19). Lastly, thank you [Joel Marcey](https://github.com/JoelMarcey) for starting Docusaurus and supporting the project all this time.
Cheers to a great 2020! 🎉

27
website/blog/2020-01-07-tribute-to-endi.md Normal file
View file

@ -0,0 +1,27 @@
---
title: Tribute to Endi
author: Joel Marcey
authorTitle: Technical Lead and Developer Advocate at Facebook
authorURL: https://github.com/JoelMarcey
authorImageURL: https://graph.facebook.com/611217057/picture/?height=200&width=200
authorTwitter: JoelMarcey
tags: [endi, tribute]
---
It is with great sadness to announce that our primary external Docusaurus contributor, [Endilie Yacop Sucipto](https://github.com/endiliey) (Endi to those who knew him), [passed away](https://give.asia/campaign/help_endi_beat_cancer#/updates) over the weekend after an illness associated with his bout with cancer.
<!--truncate-->
It is impossible to overstate Endi's impact on this project:
- Docusaurus' top contributor, [by far](https://github.com/facebook/docusaurus/graphs/contributors).
- [Lead developer](https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2) on the nearly complete [version 2 of Docusaurus](https://docusaurus.io/blog/2019/12/30/docusaurus-2019-recap).
- Overall passionate advocate of the project on [Twitter](https://twitter.com/endiliey), [Discord](https://discord.gg/docusaurus) and other social media
Thinking about it now, it is absolutely amazing how much Endi accomplished on Docusaurus given what he was battling with his health.
We are working on ways to honor Endi's contributions - a commemerative sticker, possibly - and we are open to ideas. Leave a comment here or [tweet](https://twitter.com/docusaurus) if you have a suggestion.
The Docusaurus project will not be the same without Endi, and those of us who worked with him will miss him greatly. 😔
![Endi](/img/endi.jpg)

139
website/blog/2021-01-19-docusaurus-2020-recap.md Normal file
View file

@ -0,0 +1,139 @@
---
title: Docusaurus 2020 Recap
author: Sébastien Lorber
authorTitle: Docusaurus maintainer
authorURL: https://sebastienlorber.com
authorImageURL: https://github.com/slorber.png
authorTwitter: sebastienlorber
tags: [recap]
image: /img/docusaurus-2020-recap.png
---
**2020 was great for Docusaurus**, despite [a regrettable start](https://docusaurus.io/blog/2020/01/07/tribute-to-endi) and a tumultuous year for everyone.
We continued to invest in [Docusaurus 2](https://docusaurus.io/), and made it reach **full feature parity** with [Docusaurus 1](https://v1.docusaurus.io/).
We now **recommend Docusaurus 2** as the **default choice** to start a new Docusaurus project and encourage v1 users to [migrate to Docusaurus 2](https://docusaurus.io/docs/migration).
We are **still in alpha**, but expect **some good news very soon**!
![Docusaurus v1 vs v2 npm trends](/img/blog/2020-recap/docusaurus-plushie-banner.jpeg)
<!--truncate-->
## Docusaurus 2 highlights
We have worked on many features this year, and would like to highlight the most significant ones:
- **i18n**: easily translate your Docusaurus site, released soon! ([preview](https://github.com/facebook/docusaurus/pull/3325), [doc](https://docusaurus.io/docs/next/i18n/introduction))
- **Version dropdown**: enable contextual version switch
- **Versioning options**: solving the most common pain-points users had with versioning
- **Contextual search**: search in the current version, use the brand-new DocSearch 3 experience
- **Markdown pages**: use Markdown instead of React components to create standalone pages
- **Better theme**: various UI, UX and accessibility improvements
- **PWA**: add offline support to your site, and make it installable
- **Fail-fast**: strict config validation, detect broken links, and prevent bad production deployments
- **Multi-instance**: use the docs plugin twice on a single site (e.g. iOS/Android SDK docs)
- **Migration CLI**: automate the upgrade from Docusaurus 1
- **CodeSandbox**: assess Docusaurus easily from your browser with [new.docusaurus.io](https://new.docusaurus.io/)
- **Canary releases**: use the `@canary` npm tag to use the upcoming release before anyone else
- **TypeScript**: progressive adoption for internal code, and improve usage for users
- **Publish Infima**: it is now [open-source](https://github.com/facebookincubator/infima)
## Docusaurus 2 growth
The plan to [rebuild Docusaurus from scratch in 2019](https://docusaurus.io/blog/2019/12/30/docusaurus-2019-recap) paid off: after a slow start, Docusaurus 2 has been widely adopted and has **already outgrown Docusaurus 1** usage.
![Docusaurus v1 vs v2 npm trends](/img/blog/2020-recap/docusaurus-npm-trends.png)
Notable **projects, startups, large companies, and individuals** adopted Docusaurus 2 ([showcase](https://docusaurus.io/showcase)):
- [Supabase](https://supabase.io)
- [React Navigation](https://reactnavigation.org)
- [React Redux](https://react-redux.js.org/)
- [Vector](https://vector.dev)
- [Algolia DocSearch](https://docsearch.algolia.com)
- [SAP Cloud SDK](https://sap.github.io/cloud-sdk)
- [Palo Alto Cortex XSOAR](https://xsoar.pan.dev)
- [Quddús George's website](https://portfoliosaurus.now.sh)
We helped **large scale Docusaurus 1 sites to upgrade**, ensuring a proper **migration path** and **feature parity**.
[React Native](https://reactnative.dev/) was successfully upgraded to Docusaurus 2 ([archived v1 site](http://archive.reactnative.dev/)):
![React Native screenshot](/img/blog/2020-recap/react-native-screenshot.png)
Localized Docusaurus 1 sites (like **Jest**) will be able to upgrade too:
![Jest in Japanese screenshot](/img/blog/2020-recap/jest-screenshot.png)
We also saw the **[first right-to-left](https://datagit.ir/)** Docusaurus 2 site published:
![Datagit screenshot](/img/blog/2020-recap/datagit-rtl-screenshot.png)
## GitHub Activity
- **Stars**: 14632 -> 20946 (+43.2% y/y)
- **Total Contributors**: 303 -> 512 (+68.9% y/y). Most of which are non-Facebook contributors
- **Weekly npm Downloads**: 2356 -> 25592 (+986% y/y)
- **On GitHub**, Docusaurus 1 is used by 6311 projects (+62.9% y/y) while Docusaurus 2 is used by 5039 projects (+1940% y/y)
## Collaboration with Major League Hacking
We have welcomed [Major League Hacking](https://mlh.io/) (MLH) fellows for 2 seasons already.
We are very thankful for the **various contributions** they made, such as:
- Writing the foundations of the v1 to v2 migration CLI
- Help migrate the React Native website from v1 to v2
- Making the config validation more strict and exhaustive, returning helpful error messages
- Adding CodeSandbox support
- Improving the CI pipelines: build size and Lighthouse bots
We look forward to continuing this collaboration in 2021.
## Media
Dmitry Vinnik (Developer Advocate @ Facebook) explains Docusaurus in [60 seconds](https://www.youtube.com/watch?v=_An9EsKPhp0) or [15min](https://www.youtube.com/watch?v=Yhyx7otSksg) videos.
Rachel Nabors (Documentation Engineer @ Facebook) talked a bit about Docusaurus in [React Native Radio 178 (podcast)](https://reactnativeradio.com/episodes/178-documenting-react-native-with-rachel-nabors-gWxwySPl), and William Candillon the [React Native website migration (video)](https://www.youtube.com/watch?v=-zhjq2ECKq4).
Many blog posts have been published:
- [To the Makers of Docusaurus](https://portfoliosaurus.now.sh/blog/toTheMakers) by Quddus George
- [Richer API documentation with Redoc and Docusaurus](https://davidgoss.co/blog/api-documentation-redoc-docusaurus/) by David Goss
- [How to Build a Plugin for Docusaurus v2](https://aknapen.nl/blog/how-to-build-a-plugin-for-docusaurus-v2/) by Adriaan Knapen
- [React Tracked Documentation Website with Docusaurus v2](https://blog.axlight.com/posts/react-tracked-documentation-website-with-docusaurus-v2/) by Daishi Kato
- [Easy documentation with Docusaurus](https://blog.logrocket.com/easy-documentation-with-docusaurus/) by Anshul Goyal (MLH fellow)
- [Build Beautiful Documentation Websites with Docusaurus](https://lo-victoria.com/build-beautiful-documentation-websites-with-docusaurus) by Victoria Lo
## Community
The Docusaurus community continues to grow, the [Discord](https://discord.gg/docusaurus) server is quite active, and [Stack Overflow questions](https://stackoverflow.com/questions/tagged/docusaurus) keep being posted.
The **modular architecture** of Docusaurus 2 allowed the community to build and publish [third-party plugins](https://docusaurus.io/community/resources#community-plugins-). As we would like to federate better our community, if you are building a plugin, please [let us know](https://github.com/facebook/docusaurus/discussions/4025).
## What's next?
As the **core features of Docusaurus 2** have finally been built, we will be able to dedicate more time to solve the pain points and bugs reported by the community, and make Docusaurus stable and convenient enough to enter the **beta and release-candidate phase**.
With proper support for **i18n and versioning**, and **large scale migrations** such as **React Native** and **Jest**, we now have a clear migration path for all Docusaurus 1 sites.
We still have a few **major features** that we would like to work on:
- [Create a theme gallery](https://github.com/facebook/docusaurus/issues/3522), make it easy to switch from one another, and include **first-class Tailwind support**
- [Upgrade to Webpack 5](https://github.com/facebook/docusaurus/issues/4027), improve performances and build times
- [Better compatibility with CommonMark](https://github.com/facebook/docusaurus/issues/3018), as MDX and makes it harder for CommonMark-based sites to adopt Docusaurus
- [Upgrade to MDX 2.0](https://github.com/facebook/docusaurus/issues/4029)
- Other tasks that we might discover during 2021
Huge thanks to the community for [their contributions in 2020](https://github.com/facebook/docusaurus/graphs/contributors?from=2020-01-01&to=2021-01-01&type=c), especially:
- [Joel Marcey](https://github.com/JoelMarcey) for creating Docusaurus and supporting the project all this time
- the core team - [Alexey Pyltsyn](https://github.com/lex111), [Sébastien Lorber](https://sebastienlorber.com), [Yangshun Tay](https://twitter.com/yangshunz)
- the Major League Hacking and Facebook interns for their significant impact
- the Algolia team for DocSearch 3 and their support
- [Bartosz Kaszubowski](https://github.com/Simek) for his investment in the React Native migration
- the whole community for their contributions, and providing support to each other
Cheers to a great 2021! 🎉

98
website/blog/2021-03-09-releasing-docusaurus-i18n.md Normal file
View file

@ -0,0 +1,98 @@
---
title: Releasing Docusaurus i18n
author: Sébastien Lorber
authorTitle: Docusaurus maintainer
authorURL: https://sebastienlorber.com
authorImageURL: https://github.com/slorber.png
authorTwitter: sebastienlorber
tags: [release, i18n]
image: /img/blog/2021-03-09-releasing-docusaurus-i18n/social-card.png
---
Today, we officially release **[Docusaurus 2 i18n](https://docusaurus.io/docs/i18n/introduction)** ([internationalization](https://en.wikipedia.org/wiki/Internationalization_and_localization)), as part of [2.0.0-alpha.71](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.71).
Docusaurus 2 has now reached **full feature parity with Docusaurus 1**. 🎉 And soon, after a few additional infrastructure updates and a bit more testing, the **first Docusaurus 2 beta** will be released.
**We went the extra mile**, and the new i18n support is **even better than in Docusaurus 1**.
In this post, we will present you the **translation workflow**, explain some **design decisions** and **showcase early adopter sites** that just went live: [Jest](https://jestjs.io/), [Redwood](https://learn.redwoodjs.com/), and [Datagit](https://datagit.ir/).
We also **dogfood** the i18n support on the **Docusaurus 2 site itself**, and this post is already available in [English](https://docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n) and [French](https://docusaurus.io/fr/blog/2021/03/09/releasing-docusaurus-i18n)!
<!--truncate-->
## Translate your site
You can translate a Docusaurus site in **3 simple steps**:
1. **Configure**: declare the default locale and alternative locales in `docusaurus.config.js`
1. **Translate**: put the translation files at the [correct filesystem location](https://docusaurus.io/docs/next/i18n/introduction#translation-files-location)
1. **Deploy**: build and deploy your site using a single or multi-domain strategy
The i18n support is **very flexible** and based on the **filesystem**.
The **[i18n tutorial](https://docusaurus.io/docs/i18n/tutorial)** is the best way to get started, and we provide help to use **[Git](https://docusaurus.io/docs/i18n/git)** or **[Crowdin](https://docusaurus.io/docs/i18n/crowdin)**.
## Design decisions
The goals of the Docusaurus i18n system are:
- **Simple**: just put the translated files in the [correct filesystem location](https://docusaurus.io/docs/next/i18n/introduction#translation-files-location)
- **Flexible translation workflows**: use Git (monorepo, forks, or submodules), SaaS software, FTP
- **Flexible deployment options**: single, multiple domains, or hybrid
- **Modular**: allow plugin authors to provide i18n support
- **Low-overhead runtime**: documentation is mostly static and does not require a heavy JS library or polyfills
- **Scalable build-times**: allow building and deploying localized sites independently
- **Localize assets**: an image of your site might contain text that should be translated
- **No coupling**: not forced to use any SaaS, yet integrations are possible
- **Easy to use with [Crowdin](https://crowdin.com/)**: multiple Docusaurus 1 sites use Crowdin, and should be able to migrate to v2
- **Good SEO defaults**: we set useful SEO headers like [`hreflang`](https://developers.google.com/search/docs/advanced/crawling/localized-versions) for you
- **RTL support**: locales reading right-to-left (Arabic, Hebrew, etc.) are supported and easy to implement
- **Default translations**: classic theme labels are translated for you in [many languages](https://github.com/facebook/docusaurus/tree/master/packages/docusaurus-theme-classic/codeTranslations)
## Showcase
We worked with a few volunteers to **dogfood the i18n support** before releasing it.
### Jest: upgrading Docusaurus
We have made it possible to **upgrade** a **translated Docusaurus 1 site** to Docusaurus 2.
**[Jest](https://jestjs.io)**, using Docusaurus 1 and Crowdin was one of those sites.
The Docusaurus 2 migration was successful and the new site is now deployed in production ([announcement post](https://jestjs.io/blog/2021/03/09/jest-website-upgrade)).
[![Jest i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/jest.png)](https://jestjs.io)
### Redwood: adopting Docusaurus
[Redwood](https://redwoodjs.com/) is a React full-stack Jamstack framework.
They were looking for a solution to create an **internationalized learning platform**, and became early adopters of Docusaurus 2 i18n for [learn.redwoodjs.com](https://learn.redwoodjs.com/), using Crowdin to get it translated to French.
[![Redwood i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/redwood.png)](https://learn.redwoodjs.com/)
### Datagit: using LTR support
The i18n system should work with any language, including **Right-to-Left languages**.
[Datagit.ir](https://datagit.ir/) is using Farsi, and a simple configuration option is able to **flip the Docusaurus theme** to add the required Right-to-Left support.
[![Datagit i18n screenshot](/img/blog/2021-03-09-releasing-docusaurus-i18n/datagit.png)](https://datagit.ir/)
## Conclusion
We sincerely hope you will adopt and like the new i18n support.
This feature has not been an easy one, and we would like to thank everyone that got involved in this journey:
- [Alexey](https://github.com/lex111) for his help to make the i18n support exhaustive and even better than v1
- [Simen](https://github.com/SimenB) for volunteering and supporting the Jest migration
- [Claire](https://github.com/clairefro) for adopting Docusaurus 2 on the new Redwood platform and providing many feedbacks
- [Massoud](https://github.com/massoudmaboudi) for reviewing my work on LTR and adopting it on Datagit
- [Crowdin](https://crowdin.com/) for their support and willingness to improve their translation SaaS
- The Docusaurus community for their patience, and providing many useful feedbacks on Github
Thanks for reading.
🙏 And please, add your brand new i18n sites to our [showcase page](https://docusaurus.io/showcase). We accept any all polished Docusaurus site here, and we are working on a [redesign](https://github.com/facebook/docusaurus/issues/4238) allowing you to filter sites by features.

89
website/blog/2021-05-12-announcing-docusaurus-two-beta.md Normal file
View file

@ -0,0 +1,89 @@
---
title: Announcing Docusaurus 2 Beta
author: Sébastien Lorber
authorTitle: Docusaurus maintainer
authorURL: https://sebastienlorber.com
authorImageURL: https://github.com/slorber.png
authorTwitter: sebastienlorber
tags: [release, beta]
image: /img/blog/2021-05-12-announcing-docusaurus-two-beta/social-card.png
---
After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first **[Docusaurus 2 beta](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-beta.0)**.
With the announcement of this beta, the team is even more confident that Docusaurus 2 is **ready for mainstream adoption**!
![Docusaurus beta party](/img/blog/2021-05-12-announcing-docusaurus-two-beta/image_cropped.png)
<!--truncate-->
## Docusaurus adoption
**Don't fear the beta tag!**
Docusaurus 2 is widely adopted and growing fast:
[![Docusaurus growth](/img/blog/2021-05-12-announcing-docusaurus-two-beta/trend.png)](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)
To get a fuller understanding of the quality of current Docusaurus 2 sites, our new [showcase](https://docusaurus.io/showcase) page allows you to filter Docusaurus sites by features, so you may get inspired by real-world production sites with a similar use-case as yours!
Don't miss our [favorite](https://docusaurus.io/showcase?tags=favorite) sites; they all stand out with something unique:
[![Docusaurus growth](/img/blog/2021-05-12-announcing-docusaurus-two-beta/favorites.png)](https://docusaurus.io/showcase?tags=favorite)
## Why was Docusaurus v2 in alpha for so long?
It's hard to believe that the first alpha release [v2.0.0-alpha.0](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-alpha.0) was 2 years ago 😳 , unusually long for a software alpha.
As this was a substantial re-architecture of the code base, we wanted to ensure that we had confidence in the stability and features of Docusaurus 2 before moving on to a beta stage, since beta suggests a high level of quality. We are happy to say that Docusaurus 2 has reached **feature parity** with Docusaurus 1 with **[i18n](https://docusaurus.io/blog/2021/03/09/releasing-docusaurus-i18n)**, and it has been **successfully adopted** by many Docusaurus sites (see [i18n showcase](https://docusaurus.io/showcase?tags=i18n)).
We're now quite confident that the core features of Docusaurus 2 are stable enough to be in beta.
## What are the goals of the beta?
Now that Docusaurus 2 is stable and major feature complete, the goal of the beta is to inspire confidence in new users on the production-readiness of Docusaurus 2, migrate more remaining Docusaurus 1 users to version 2, and officially deprecate Docusaurus 1. We will, of course, continue to resolve any issues and bugs that may be discovered.
In addition, we will use the beta phase to **improve our theming system**.
We want to make it:
- **easier to implement a custom theme**, including for ourselves. We want to provide [multiple official themes](https://github.com/facebook/docusaurus/issues/3522) (including [Tailwind CSS](https://github.com/facebook/docusaurus/issues/2961)) for a long time.
- **safer to extend an existing theme**: it can be painful to upgrade a highly customized Docusaurus site, as customizations can conflict with internal changes. We need to make the theme public API surface more explicit, and make it clear what is safe to customize.
We will build a better **theming infrastructure** and refactor the classic theme to use it.
If you customize your site, you may find these planned improvements quite valuable.
## What's new?
In case you missed it, we recently shipped two major improvements:
- [Auto-generated sidebars](https://docusaurus.io/docs/sidebar#sidebar-item-autogenerated): no need to maintain a `sidebars.js` file anymore!
- [Webpack 5 / PostCSS 8](https://github.com/facebook/docusaurus/issues/4027): persistent caching significantly speeds up **rebuild time**!
## What's next?
Shipping the official 2.0 release!
To get there, we will continue to **fix bugs** and implement the **most wanted features**, including:
- [Sidebar category index pages](https://github.com/facebook/docusaurus/issues/2643)
- [Better mobile navigation UX](https://github.com/facebook/docusaurus/issues/2220)
- [Better admonition design](https://github.com/facebookincubator/infima/issues/55)
- [CSS-in-JS support](https://github.com/facebook/docusaurus/issues/3236)
- [Improve build time performance](https://github.com/facebook/docusaurus/issues/4765)
- [Extend Docusaurus plugins, CMS integration](https://github.com/facebook/docusaurus/issues/4138)
- [Fix trailing slashes and relative link issues](https://github.com/facebook/docusaurus/issues/3372)
- [Better compatibility with CommonMark](https://github.com/facebook/docusaurus/issues/3018)
- [Upgrade to MDX 2.0](https://github.com/facebook/docusaurus/issues/4029)
## Conclusion
This is an exciting time for Docusaurus.
We are inspired by the [positive feedback](https://twitter.com/sebastienlorber/timelines/1392048416872706049) about Docusaurus, and discover new sites online every single day.
We are so excited for this beta release. We strove for quality and stability while continuing to try to increase the adoption of Docusaurus. For those that have been on the fence from migrating an existing Docusaurus site to Docusaurus 2, it is a great time to upgrade. We want you running on the latest infrastructure when we deprecate Docusaurus 1 at the end of this beta period. Let us know how we can help.
Thank you to everyone for reading and to the entire community who supports Docusaurus. 🤗