Joel Marcey

Today we are extremely happy to finally announce Docusaurus 2.0! 🥳️

Chez Meta Open Source, nous pensons que Docusaurus vous aidera à construire les meilleurs sites web de documentation avec un minimum d'effort, vous permettant de vous concentrer sur ce qui compte vraiment : l'écriture du contenu.

After 4 years of work, 75 alphas and 22 betas, the next generation of Docusaurus is ready for prime time. From now on, we now plan to respect Semantic Versioning and will release major versions more frequently.

We are on ProductHunt and Hacker News!

Now is the best time to show your love for Docusaurus!

Qu'est-ce que Docusaurus exactement ?​

Docusaurus is a static site generator that helps you ship beautiful documentation websites in no time.

Focus on your content: just write Markdown files. Docusaurus will generate an optimized website for you that's easy to host anywhere.

Docusaurus is full-featured and very flexible: we ship with well-designed docs and blog layout, as well as out-of-the-box versioning, search, and internationalization functionalities, with a call to accessibility and search engine optimizations. Its flexible theming system permits to adapt the UI to match your branding so that it integrates nicely with your main website or documentation portal. Its usage of React enables a modern client-side navigation, and the ability to build an interactive documentation.

The Docusaurus philosophy is akin to the Pareto principle: you can get 80% of the results for 20% of the effort. This enables you to compete with top-notch documentation sites with minimal effort.

Docusaurus aims to be the best documentation tool, but you can use it for other use-cases as well: a blog, a knowledge base, a developer portfolio, a second brain, or even to scaffold landing pages!

L'histoire de Docusaurus​

Docusaurus was created at Facebook Open Source in 2017 (now Meta Open Source). Nous avions beaucoup de projets internes et open source à documenter. It's complicated enough to write good documentation, let alone to create the HTML, CSS, and JavaScript for a good-looking website. We wanted project leaders to be able to focus on the content, and Markdown is great for that.

At that time, our solution was to copy/paste a Jekyll template over and over again. This naturally became hard to maintain, so we created a tool to solve our own pain once for all.

Docusaurus v1 was born!

It quickly built momentum at Facebook and in the frontend ecosystem, adopted by many popular projects such as Prettier, Babel, React-Native, KaTeX, and of course Docusaurus v1 itself.

En route vers Docusaurus 2.0​

Docusaurus v1 has been very successful, but we started to question some architectural choices:

• React was only used as a server-side templating language, and not used on the client
• Theming system was pretty limited, and apart from changing a few colors with CSS, it was difficult to do more advanced customizations
• The docs versioning system was confusing, since it was based on a diff algorithm
• The codebase was monolithic, neither well-tested nor easy to extend

Docusaurus v2 was rebuilt from the ground up with a new modular architecture:

• React is now also used on the client, enabling a modern Single Page Application navigation
• Plugins empower the community to contribute useful features as third-party packages
• Theming is more flexible than ever
• Le versionnage des documents est désormais basé sur des copies instantanées, ce qui est beaucoup plus facile à comprendre
• We kept everything good from v1: docs, blog, pages, versioning, i18n...
• We implemented several new features

More details in the Docusaurus 2 project announcement and v1 to v2 migration guide

Qui utilise Docusaurus 2.0 ?​

Despite being in pre-release, it didn't take long for Docusaurus v2 to outgrow Docusaurus v1 in terms of NPM downloads:

La tendance de nos étoiles GitHub est très positive, en concurrence avec les principaux frameworks :

Actuellement, Docusaurus v2 est déjà un grand succès avant même son lancement :

• We received so many lovely testimonials
• Companies like 1Password and Courier are writing down their positive experience
• Our site showcase references hundreds of sites, and this is only the tip of the iceberg.

Quoi de neuf dans la 2.0 ?​

Il serait difficile de décrire toutes les nouvelles fonctionnalités de Docusaurus v2. Let's focus on the features we believe are the most impactful.

MDX​

MDX allows you to interleave React components in Markdown. This enables you to build top-notch interactive documentation experiences very easily.

Une démo vaut mieux qu'un long discours :

### Give it a try: press that button!

import ColorModeToggle from '@theme/ColorModeToggle';

<ColorModeToggle/>

Conventions du système de fichiers​

Our goal is to make Docusaurus very intuitive to use. Nous avons ajouté des conventions de système de fichiers et l'ajout d'une page de doc est aussi simple que la création d'un fichier Markdown.

Plugins​

Docusaurus now has a modular architecture with a plugin system — our core features like docs, blog, pages, and search are all powered by individual plugins.

More importantly, it enables our community to enhance Docusaurus with additional features.

Soulignons quelques exemples :

• redocusaurus: seamless integration with OpenAPI and Redoc

• docusaurus-preset-shiki-twoslash: use Shiki code block syntax highlighting with TwoSlash TypeScript compiler hints

• docusaurus-search-local: one of the various local search alternatives to the built-in Algolia plugin

Thème​

Theming is one of the most important features of Docusaurus: we believe a professional documentation site should respect your company's branding and create a consistent experience.

Docusaurus theming gives a lot of flexibility on multiple levels:

• Personnalisez les variables CSS pour ajuster les couleurs, les polices et plus encore
• Fournissez vos propres feuilles de style CSS
• Implémentez votre propre thème à partir de zéro
• Override any React component provided by our default theme: we call this swizzling

This enables users willing to invest a bit more time on customizations to build sites that look different from others.

Autres fonctionnalités​

Docusaurus 2 est doté d'une très longue liste de fonctions utiles :

• Theme: dark mode, better UI and UX, flexible themeConfig options...
• Versionnage des docs : options du plugin flexibles pour s'adapter à votre flux de travail
• Barre latérale des docs : catégorie repliable, pages d'index des catégories...
• Blog : auteurs multiples, carte des auteurs, page d'archives...
• Markdown : onglets, équations mathématiques, blocs de code en direct, liens, frontmatter flexible...
• Recherche : utilisez la nouvelle expérience Algolia DocSearch 3
• Ressources : facilitez l'incorporation d'images et d'autres types de fichiers
• Internationalisation : options de configuration, traductions du thème par défaut...
• Accessibilité : étiquettes aria, contrastes des couleurs, saut vers le contenu, navigation par le clavier, amélioration progressive...
• Référencement : valeurs par défaut judicieuses, facile à personnaliser, url canonique, carte sociale, no-index, sitemap, microdata, hreflang...
• PWA : ajoute la prise en charge hors ligne à votre site et le rend installable
• Echec rapide : validation stricte de la configuration, détection des liens erronés et prévention des mauvais déploiements en production
• Prise en charge de TypeScript pour les fichiers de configuration, les plugins, les pages personnalisées et les auteurs de thèmes
• Playgrounds: assess Docusaurus easily from your browser with docusaurus.new
• Versions canary : utilisez la balise @canary avec npm pour utiliser la prochaine version avant tout le monde
• Des tests : Docusaurus est bien testé, nous testons les fonctionnalités et nous nous assurons qu'elles fonctionnent toujours

Pourquoi la 2.0 maintenant ?​

Many enthusiastic followers of ours have been curious why it took us 4 years to release Docusaurus 2.0, considering the beta is already successful and widely used in production.

The reason is that we aim to respect Semantic Versioning, which means we will be incrementing the major version number whenever we release a breaking change.

C'est important pour plusieurs raisons :

• It guarantees simple minor version upgrades, as long as you only use the public API
• Il respecte les conventions de l'écosystème front-end
• Une nouvelle version majeure est l'occasion de documenter minutieusement les changements de rupture
• Une nouvelle version majeure ou mineure est l'occasion de communiquer les nouvelles fonctionnalités par le biais d'un article du blog

The problem is that our flexible theming system inherently creates a very implicit API surface on which it is hard to know what is a breaking change in the first place. Les sites Docusaurus hautement personnalisés ont parfois du mal à mettre à jour Docusaurus parce qu'ils réalisent des personnalisations en utilisant des API internes. We dedicated time to extensive theme refactors and clearly defining our public API, so that future code changes can be made more safely. Nous continuerons à développer cette API publique de thématisation afin que les personnalisations de site les plus courantes n'aient pas besoin d'utiliser d'API interne.

Quelle est la prochaine étape ?​

Le travail sur Docusaurus 3.0 a commencé, et cette prochaine version ne sortira que dans quelques mois. We will backport retro-compatible changes in Docusaurus 2.x minor versions to make them available as soon as possible to the community on a stable channel.

Un échantillon des fonctionnalités figurant sur notre feuille de route pour les prochaines versions majeures de Docusaurus :

• Upgrade to MDX 2.0
• Improve Markdown infrastructure
• Improve theming and swizzle
• TailwindCSS theme
• Theme; support custom item types for navbar, doc sidebar, blog sidebar, footer
• Dynamic navbar: navbar item activation strategies
• Custom Social Cards
• CSS-in-JS support
• Use Node.js ES Modules
• Improve build time performance
• Extend Docusaurus plugins, CMS integration

Merci​

We'd like to express our gratitude to all our contributors, including:

• The Docusaurus core team: Alexey Pyltsyn, Joshua Chen, Sébastien Lorber, Yangshun Tay and all our former team members
• Joel Marcey for creating Docusaurus 1.0 and supporting the Docusaurus 2.0 project at Meta Open Source
• Paul O’Shannessy for supporting the development of all the next versions of Docusaurus at Meta Open Source
• Eric Nakagawa for creating our cutest mascot Slash
• Endilie Yacop Sucipto for his significant initial work on Docusaurus v2
• Clément Vannicatte, Kevin Granger and the whole Algolia team for their support
• All the community members for making valuable code contributions, improving our documentation, and answering questions on Discord

We'd like to thank in particular all our Docusaurus 2.0 early adopters for assessing its alpha, beta and canary releases, providing a ton of invaluable feedback. Nous espérons sincèrement que vous avez eu une agréable expérience en l'utilisant, et que vous continuerez à nous faire part de vos commentaires sur les prochaines préversions de Docusaurus 3.0.

At Meta Open Source, Docusaurus is one of our most successful projects. Nous sommes impatients de voir tous les sites de documentation exceptionnels que vous allez créer ! Don't forget to submit them to our site showcase!

Now, let your imagination run wild 🤪!

— Slash

We are on ProductHunt and Hacker News!

🙏 Partagez votre expérience d'utilisation de Docusaurus avec la communauté !

After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.

With the announcement of this beta, the team is even more confident that Docusaurus 2 is ready for mainstream adoption!

It is with great sadness to announce that our primary external Docusaurus contributor, Endilie Yacop Sucipto (Endi to those who knew him), passed away over the weekend after an illness associated with his bout with cancer.

Docusaurus went live on December 14, 2017. At the time, we had 8 early adopters.

We are very happy to introduce Docusaurus to help you manage one or many open source websites.

We created Docusaurus for the following reasons:

1. Mettre l'accent sur la rédaction d'une bonne documentation au lieu de s'inquiéter de l'infrastructure d'un site Web.
2. Fournir des fonctionnalités dont bon nombre de nos sites web open source ont besoin comme le support des blogs, la recherche et la mise en page.
3. Faciliter l'envoi de mises à jour, de nouvelles fonctionnalités et de corrections de bogues pour tout le monde en même temps.
4. Et enfin, donner une apparence et une sensation cohérentes à tous nos projets open source.