![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-5214adcb56c496fa6afc571fb4d378f6.png\")
We are happy to announce Docusaurus 3.6.
\nDocusaurus is now ⚡️⚡️⚡️ much faster to build your site.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n
This release has been mostly focused on build performance through the Docusaurus Faster project.
\nThe Docusaurus Faster project's goal is to reduce the build times and memory consumption.
\nWe have worked on multiple optimizations and modernized our infrastructure to use faster Rust-based tools, notably:
\nAdopting a new infrastructure can have various impacts. It's impossible to list them all exhaustively, so let's focus on the major ones.
\nTo help you adopt it easily, we have been fairly conservative in terms of expected static site output and browser support.
\nBenchmarks on community site show that you can expect your production site to build ⚡️2 to 4 times faster! 🔥:
\nRspack doesn't support persistent caching yet, but it's on the roadmap and should be implemented soon. We think it's not a problem for the adoption of Rspack considering a cold Rspack build is usually as fast as a warm Webpack build using persistent caching.
You should also notice an improvement in memory consumption:
\nprocess.exit(0) that can hide memory leaks in your own code and third-party pluginsThis new infrastructure is a breaking change, but it is opt-in and does not require a new major version of Docusaurus.
\nBefore using Docusaurus Faster, add this new package:
\nnpm install @docusaurus/faster
yarn add @docusaurus/faster
pnpm add @docusaurus/faster
To help you adopt it incrementally under Docusaurus v3, we're introducing a set of feature flags that you can activate progressively.
\nWe recommend turning them on all at once with this simple boolean shortcut:
\nconst config = {
future: {
experimental_faster: true,
},
};
In case one of the flags does not work for your site, it's possible to turn feature flags on independently:
\nconst config = {
future: {
experimental_faster: {
swcJsLoader: true,
swcJsMinimizer: true,
swcHtmlMinimizer: true,
lightningCssMinimizer: true,
rspackBundler: true,
mdxCrossCompilerCache: true,
},
},
};
swcJsLoader: Use SWC to transpile JS (instead of Babel)swcJsMinimizer: Use SWC to minify JS (instead of Terser)swcHtmlMinimizer : Use SWC to minify HTML and inlined JS/CSS (instead of html-minifier-terser)lightningCssMinimizer: Use Lightning CSS to minify CSS (instead of cssnano and clean-css)rspackBundler: Use Rspack to bundle your app (instead of webpack)mdxCrossCompilerCache: Compile MDX files once for both browser/Node.js environments instead of twiceDon't be afraid to turn this feature on. What's experimental is the config options.
The new infrastructure is robust and well-tested by our CI pipeline. The Docusaurus site already uses it in production, and we plan to use it on other Meta docs sites as well.
The new infrastructure uses Rspack. By chance, Rspack is almost 100% compatible with webpack, and Rspack shouldn't break our plugin ecosystem.
\nMost Docusaurus plugins should work out of the box with Rspack, even those implementing configureWebpack.
However, some of them will require small modifications to make them compatible with Rspack. The general idea is to avoid importing webpack directly, and use the \"dynamically provided\" webpack instance instead:
-import webpack from 'webpack';
export default function (context, options) {
return {
name: 'custom-docusaurus-plugin',
- configureWebpack(config, isServer) {
+ configureWebpack(config, isServer, {currentBundler}) {
return {
plugins: [
- new webpack.DefinePlugin({}),
+ new currentBundler.instance.DefinePlugin({}),
]
};
},
};
}
Check the dedicated issue for guidelines and support.
It's only the beginning: we will continue working on the Docusaurus Faster project and already have a few more performance improvements planned.
\nDepending on your feedback, we plan to make this new infrastructure the default in an upcoming major version of Docusaurus.
\n🙏 We'd like to thank the authors of all these great tools that already helped us make Docusaurus much faster than before. In particular the Rspack team that supported us along the way, handled our feedback very quickly and implemented all the missing features we needed to make it happen. 👏
\nIn #10588, we created a Docusaurus plugin for Rsdoctor. It analyzes the bundling phase of Docusaurus and helps you figure out what slows down the bundler in terms of loaders, plugins and minimizers. It works for both webpack and Rspack.
\n![\"Loader](\"https://docusaurus.io/fr/assets/images/rsdoctor-36963a4eaca95f83538208463e62eae2.jpg\")
To use it, install the new @docusaurus/plugin-rsdoctor package, and then use the plugin in your config:
export default {
plugins: [
[
'rsdoctor',
{
/* options */
},
],
],
};
Turn it on conditionally, based on an environment variable:
export default {
plugins: [
process.env.RSDOCTOR === 'true' && [
'rsdoctor',
{
/* options */
},
],
],
};
# Build without Rsdoctor
npm run build
# Build with Rsdoctor
RSDOCTOR=true npm run build
In #10510, we relaxed our Mermaid diagrams dependency range to allow newer major versions of Mermaid. We now support both Mermaid 10/11, and expect upcoming versions to be compatible, letting you upgrade on your own terms.
\nThis unlocks new types of diagrams, such as Architecture Diagrams:
\n\nVoici les autres changements notables :
\nfrontMatter.title_meta to override frontMatter.title for SEO reason.docusaurus build and docusaurus deploy now support multiple --locale CLI args.docusaurus-remark-plugin-npm2yarn upgrades to npm-to-yarn v3 and can convert npx commands.3.5.2-canary-<number> instead of 0.0.0-canary-<number> to respect plugins peerDependency constraints.@docusaurus/tsconfig upgrades to target: 'es2022'.babel.config.js from Docusaurus init templates to discourage customizing Babel.Check the 3.6.0 changelog entry for an exhaustive list of changes.
", "url": "https://docusaurus.io/fr/blog/releases/3.6", "title": "Docusaurus 3.6", "summary": "We are happy to announce Docusaurus 3.6.", "date_modified": "2024-11-04T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/releases/3.5", "content_html": "We are happy to announce Docusaurus 3.5.
\nThis release contains many new exciting blog features.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-7b2ed059f27fc8b64f3f20025ebb382f.png\")
In #10222, we added the possibility to associate social links to blog authors, for inline authors declared in front matter or global through the authors.yml file.
slorber:
name: Sébastien Lorber
# other author properties...
socials:
x: sebastienlorber
linkedin: sebastienlorber
github: slorber
newsletter: https://thisweekinreact.com
![\"Author](\"https://docusaurus.io/fr/assets/images/author-socials-93483e664b2d095b137cf10c4769c100.png\")
Icons and handle shortcuts are provided for pre-defined platforms x, linkedin, github and stackoverflow. It's possible to provide any additional platform entry (like newsletter in the example above) with a full URL.
In #10216, we added the possibility for global blog authors (declared in authors.yml) to have their own dedicated page listing all the blog posts they contributed to.
This feature is opt-in and mostly relevant for multi-author blogs. You can turn it on for a specific author by setting the page: true property:
slorber:
name: Sébastien Lorber
# the description will be displayed on the author's page
description: 'A freelance React and React-Native developer...'
page: true # Turns the feature on
This creates a dedicated author page at /blog/authors/slorber.
![\"Author](\"https://docusaurus.io/fr/assets/images/author-page-4a9753641b116ddfeecc46ed1dcee907.png\")
An authors index page is also created, listing all the blog authors.
\n![\"Author](\"https://docusaurus.io/fr/assets/images/author-index-4abd3b8b777b2c1b3958768559896262.png\")
Check the blog authors pages guide for details.
\nIn #9252, we added support for styling your blog feeds by providing custom XSLT .xls files for the RSS and Atom feeds. This allows browsers to render the feeds in a more visually appealing way, like a regular HTML page, instead of the default XML view.
const blogOptions = {
feedOptions: {
xslt: {
rss: 'custom-rss.xsl',
atom: 'custom-atom.xsl',
},
},
};
Writing your own XSLT can be complex, but you can also use xslt: true to turn on the built-in style:
const blogOptions = {
feedOptions: {
xslt: true,
},
};
![\"Screenshot](\"https://docusaurus.io/fr/assets/images/blog-feed-xslt-22194c2a971aba7f3bbf6115d3aa1d49.png\")
In #10252, we added support for grouping blog posts by years in the blog sidebar.
\n![\"Screenshot](\"https://docusaurus.io/fr/assets/images/blog-sidebar-years-1d0be02836d9a3307386c365b9969a37.png\")
This feature is now turned on by default, but can be disabled with themeConfig.blog.sidebar.groupByYear: false.
We added new blog options to enforce recommended practices for your blog posts:
\nonInlineAuthorsWe believe large multi-blogs are easier to manage by using global authors, declared in authors.yml. This notably permits to avoids duplicating author information across multiple blog posts, and now permits to generate author pages.
In #10224, we added the onInlineAuthors option. Use onInlineAuthors: 'throw' to forbid inline authors, and enforce a consistent usage of global authors.
onUntruncatedBlogPostsWe believe blog posts are better using truncation markers (<!-- truncate --> or {/* truncate */}). On paginated lists (blog home, tags pages, authors pages), this permits to render a more concise preview of the blog post instead of a full blog post.
In #10375, we added the onUntruncatedBlogPosts option. Use onUntruncatedBlogPosts: 'throw' to enforce a consistent usage of truncation markers.
Voici les autres changements notables :
\n# title are automatically wrapped in <header> for consistency with front matter title: Title.null.recmaPlugins option to modify the MDX Estree AST._category_.json accepts a new description property that gets displayed on generated index pages.docusaurus --version now actually returns the Docusaurus version.mdx-code-block now supports indentation.<TabItem lazy> support the for className prop.@docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-blog/client.@docusaurus/theme-common/internal APIs have been moved to @docusaurus/plugin-content-docs/client.Check the 3.5.0 changelog entry for an exhaustive list of changes.
", "url": "https://docusaurus.io/fr/blog/releases/3.5", "title": "Docusaurus 3.5", "summary": "We are happy to announce Docusaurus 3.5.", "date_modified": "2024-08-09T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/releases/3.4", "content_html": "We are happy to announce Docusaurus 3.4.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-66116702bb73f0bf68a095ddaecc0fe4.png\")
The docs and blog plugins both already supported a tags front matter attribute, enabling you to group related content. But tags declared inline in the front matter are not always ideal.
With #10137, you can now declare a list of pre-defined tags in a tags.yml file:
tag1:
label: 'Tag 1'
description: 'Tag 1 description'
permalink: /tag-1-permalink
tag2:
label: 'Tag 2'
description: 'Tag 2 description'
permalink: /tag-2-permalink
These predefined tags can be used in the front matter of your blog or docs files:
\n---
tags: [tag1, tag2]
---
# Title
Content
Use the new onInlineTags: 'throw' plugin option to enforce the usage of predefined tags and prevent contributors from creating new unwanted tags.
With 9859, we added a new experimental hash router config option, useful for offline browsing by opening your site locally through the file:// protocol.
export default {
future: {
experimental_router: 'hash',
},
};
This mode is not recommended for sites deployed through a web server.
When this mode is turned on, Docusaurus will opt out of static site rendering, and build a client-side single page application where all routes are prefixed with /#/. A single index.html file is generated. This file can be opened locally in your browser by simply clicking it, using the browser file:// protocol. This makes it possible to distribute a Docusaurus site as a .zip file so that readers can browse it offline, without having to install anything complex on their computer apart a web browser.
![\"Docusaurus](\"https://docusaurus.io/fr/assets/images/hash-96c9ef1044dc1febfe3eefdc9350e2a0.png\")
Try browsing our own Docusaurus site built with the hash router:
\nThis feature is experimental. If you try it out, please let us know how it works for you here.
Docusaurus uses the browser localStorage API to persist UI state.
But sometimes the storage space is \"shared\" between multiple sites using the same domain, leading to storage key conflicts. This generally happens in two cases
\nhttp://localhost:3000 siteshttps://example.com/site1/ and https://example.com/site2/For this reason, we introduced a new experimental siteStorage configuration option:
export default {
future: {
experimental_storage: {
type: 'localStorage',
namespace: true,
},
},
};
When namespace: true is set, we apply a hash suffix to all the storage keys, making them unique to the current site (based on config.url and config.baseUrl. For example, the theme storage key becomes theme-x6f. It is also possible to provide your own custom suffix namespace: 'suffix'. We also made it possible to use type: 'sessionStorage' instead of the default localStorage.
This feature is experimental. If you try it out, please let us know how it works for you here.
Voici les autres changements notables :
\n/search page now respects the contextualSearch: false settingCheck the 3.4.0 changelog entry for an exhaustive list of changes.
", "url": "https://docusaurus.io/fr/blog/releases/3.4", "title": "Docusaurus 3.4", "summary": "We are happy to announce Docusaurus 3.4.", "date_modified": "2024-05-31T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/releases/3.3", "content_html": "Nous sommes heureux d'annoncer Docusaurus 3.3.
\nUpgrading should be easy. Our release process respects Semantic Versioning. Minor versions do not include any breaking changes.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-105335e6b4ebb3f62aa9b04e33a76dea.png\")
The React core team recently released the first React 19 beta. They also published an upgrade guide and a React v18.3 release with new warnings to help us identify issues before upgrading to React 19.
\nDocusaurus v3 depends on React 18.x. When initializing a new Docusaurus sites, it will use that new React 18.3 release. It's also the case if you decide to upgrade your dependencies, or re-generate your package manager lockfile.
It turns out in its current state, Docusaurus had a few of those extra warnings to fix, notably this one immediately appearing on your dev console on any page load and navigation:
\n\n\nWarning: LoadableComponent uses the legacy contextTypes API which is no longer supported and will be removed in the next major release. Use React.createContext() with static contextType instead.
\n
In #10079, we got Docusaurus ready for React 19. We fixed all the React 18.3 warnings we encountered. In case we missed any, don't hesitate to report new warnings if you see them, to us but also to other Docusaurus third-party plugin authors.
\ncreateSitemapItemsIn #10083, we introduced a new flexible createSitemapItems() hook to the sitemap plugin. This enables users to create/filter/transform/enhance the sitemap items with their own custom logic.
export default {
presets: [
[
'@docusaurus/preset-classic',
{
sitemap: {
createSitemapItems: async ({
defaultCreateSitemapItems,
...params
}) => {
const items = await defaultCreateSitemapItems(params);
return items.filter((item) => !item.url.includes('/tags/'));
},
},
},
],
],
};
The Docusaurus pages plugin has historically been lagging behind the docs and blog plugins in terms of available feature.
\nIn #10032 we normalized the options available on each core content plugins by adding a few the missing page plugins APIs related to the edit url and the last update metadata displayed at the bottom on Markdown pages.
\nexport default {
presets: [
[
'@docusaurus/preset-classic',
{
pages: {
editUrl:
'https://github.com/facebook/docusaurus/tree/main/website/src/pages',
editLocalizedFiles: true,
showLastUpdateAuthor: true,
showLastUpdateTime: true,
},
},
],
],
};
These new plugin options only apply to Markdown pages, and have no effect on React pages for which you have full control over the layout with JSX.
Voici les autres changements notables :
\nsiteConfig.markdown.anchors.maintainCasedocusaurus deploy --target-dir optionroute.props<Admonition> component can render properly without heading/icon<Tabs> props can now override defaultsdocusaurus serve works better with a /baseUrl/ pathname prefixpt-BRCheck the 3.3.0 changelog entry for an exhaustive list of changes.
", "url": "https://docusaurus.io/fr/blog/releases/3.3", "title": "Docusaurus 3.3", "summary": "Nous sommes heureux d'annoncer Docusaurus 3.3.", "date_modified": "2024-05-03T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/releases/3.2", "content_html": "We are happy to announce Docusaurus 3.2.
\nLa mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-8ca15c1adaeb77ca302178575136a0b6.png\")
We worked hard to reduce the time it takes to build a Docusaurus site in production mode.
\nBetween v3.1.0 and v3.2.0, several changes have been made, leading to significantly faster production builds for many sites.
\nLet's take an example. Our benchmark on the React Native website upgrading to v3.2 reports the following results:
\nThe results will vary depending on your site's topology and the options you turned on, but we expect the largest sites will see the most significant improvements.
\nNote that this is only the beginning, and Docusaurus performance can still be significantly improved, notably the bundling time and the memory consumption. Track our performance issue for upcoming improvements.
\nA cold build is when the Docusaurus caches are empty, generally after running docusaurus clear.
An incremental build happens when you run another time the docusaurus build command. Docusaurus automatically tries to \"re-use\" computations from former builds to make subsequent builds faster. In practice it's based on Webpack persistent caching. To enable incremental builds on your CI server, you can persist the node_modules/.cache folder across builds.
We also worked on improving the performance of the dev server, so that you can get a faster feedback when editing Markdown/MDX files.
\nThe way we initially implemented content reloading wasn't great. For example, editing a blog post file would also trigger a useless reload of the unrelated docs plugin. From now on, when editing a plugin's content, only that plugin will reload. It's hard to measure precisely the impact of this change, but I estimate edits should appear in your browser at least 50% faster 🔥.
\nWe plan to keep improving the speed of our dev server, with even more granular hot reloads, ensuring we don't run useless computations that would always keep giving the same result.
\nWith #9684, Docusaurus is now able to render headings coming from an imported partial into the table-of-contents.
\nDocusaurus and MDX allows you to import one Markdown file into another. We usually call the imported Markdown file a \"partial\", and use the _ prefix so that this file does not lead to the creation of a new page.
# My Doc
## Doc heading
Content is imported from another MDX file:
import ImportedDoc from './\\_importedDoc.mdx';
<ImportedDoc />
## Partial heading
Some paragraph
Previously, the heading Partial heading did not appear in the table-of-contents, but now it will!
We improved the blog plugin with several new options to make it even more powerful and flexible:
\nprocessBlogPosts option allow you to filter/transform/sort blog posts.pageBasePath option allows you to customize the blog pagination URL segment (/blog/page/2)With #9954, the sitemap plugin has a new lastmod option that can now emit a <lastmod> tag on the XML. The value is read from the Git history by default, but can be overridden with docs and blog last_update front matter.
We also made it possible to opt-out of emitting <priority> and <frequency> tags, which are generally ignored by crawlers (notably Google).
We recommend using the following sitemap plugin config, that will become the default in Docusaurus V4:
\n{
lastmod: 'date',
priority: null,
changefreq: null,
}
docusaurus swizzle and create-docusaurus CLIs now ask users if they prefer to use TypeScriptallContentLoaded plugin lifecycle (experimental)Check the 3.2.0 changelog entry for an exhaustive list of changes.
", "url": "https://docusaurus.io/fr/blog/releases/3.2", "title": "Docusaurus 3.2", "summary": "We are happy to announce Docusaurus 3.2.", "date_modified": "2024-03-29T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/releases/3.1", "content_html": "Nous sommes heureux d'annoncer Docusaurus 3.1.
\nLa mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-e1b6e0c51be29d4ab2d4c966d220410c.png\")
Dans le #9528, nous avons amélioré le vérificateur intégré de liens défectueux pour qu'il détecte également les ancrages défectueux.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/broken-anchor-4191e5dd94aef9e8c5e3524880670f0f.jpg\")
La nouvelle option onBrokenAnchors a la valeur par défaut warn pour des raisons de rétro-compatibilité.
Nous recommandons de le changer en throw et de faire échouer vos constructions CI au lieu de déployer des ancrages défectueux vers les productions.
Pour les utilisateurs et les auteurs de plugins qui implémentent des composants <Heading> et <Link> personnalisés, nous fournissons une nouvelle API de hook React useBrokenLinks.
La plupart des utilisateurs de Docusaurus n'ont pas besoin de s'en préoccuper, les composants intégrés (docusaurus/Link et @theme/Heading) l'utilisent déjà en interne.
parseFrontMatterDans le #9624, nous avons ajouté une nouvelle fonction hook siteConfig.markdown.parseFrontMatter.
Cela permet de mettre en œuvre des transformations pratiques du front matter, des raccourcis, ou de s'intégrer à des systèmes externes utilisant le front matter que les plugins de Docusaurus ne prennent pas en charge.
\nexport default {
markdown: {
parseFrontMatter: async (params) => {
// Réutiliser l'analyseur par défaut
const result = await params.defaultParseFrontMatter(params);
// Traiter les placeholders de description de la page de garde
result.frontMatter.description =
result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');
// Créer votre propre raccourci pour les pages de garde
if (result.frontMatter.i_do_not_want_docs_pagination) {
result.frontMatter.pagination_prev = null;
result.frontMatter.pagination_next = null;
}
// Renommer un front matter non supporté provenant d'un autre système
if (result.frontMatter.cms_seo_summary) {
result.frontMatter.description = result.frontMatter.cms_seo_summary;
delete result.frontMatter.cms_seo_summary;
}
return result;
},
},
};
Lisez le guide du front matter et la référence de l'API parseFrontMatter pour plus de détails.
Voici les autres changements notables :
\nsiteConfig.markdown.remarkRehypeOptions pour passer des options à remark-rehype, ce qui permet de personnaliser des choses comme le libellé de la note de bas de page MDXPORTConsultez l'entrée 3.1.0 du journal des modifications pour une liste exhaustive des changements.
", "url": "https://docusaurus.io/fr/blog/releases/3.1", "title": "Docusaurus 3.1", "summary": "Nous sommes heureux d'annoncer Docusaurus 3.1.", "date_modified": "2024-01-05T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/releases/3.0", "content_html": "Aujourd'hui, nous sommes heureux d'annoncer Docusaurus 3.0 ! 🥳
\nChez 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.
\nIl s'agit d'une nouvelle version majeure de Docusaurus, avec de nouvelles fonctionnalités intéressantes et des dépendances mises à jour.
\nConformément aux principes du Semantic Versioning, cette version inclut des changements de rupture que nous avons documentés en détail dans le guide de mise à jour de la version 3. Les changements de rupture peuvent être gênants, mais ils sont nécessaires pour préparer le terrain à une nouvelle vague de fonctionnalités Docusaurus que nous prévoyons d'implémenter.
\n![\"image](\"https://docusaurus.io/fr/assets/images/social-card-75819f68ecbb579fe176843bb2e3df82.png\")
Nous avions initialement prévu de publier des versions majeures plus fréquemment, mais Docusaurus v3 a pris plus de temps que prévu. Parmi les changements de rupture que nous avons comptabilisés, la montée de version vers MDX v3 est probablement le principal défi à l'adoption de cette nouvelle version. Nous avons fait un effort supplémentaire pour rendre cette montée de version aussi facile que possible, notamment en ajoutant des options de compatibilité pour MDX v1.
\nLes sites les plus simples n'auront besoin de mettre à jour que quelques dépendances npm. Pour les sites plus complexes, nous avons élaboré quelques stratégies qui peuvent vous aider à effectuer une mise à niveau en toute confiance :
\nSelon notre processus de version, Docusaurus v2 est maintenant entré en mode maintenance. Elle bénéficiera d'une assistance pour les problèmes de sécurité majeurs pendant trois mois seulement, jusqu'au 31 janvier 2024. Il est recommandé de passer à la version 3 dans ce laps de temps.
Cette section ne donne qu'un bref aperçu. Toutes les changements de rupture sont documentés en détail dans le guide de mise à jour de la version 3.
\nDocusaurus v3 a mis à jour quelques dépendances vers de nouvelles versions majeures, chacune venant avec ses propres changements de rupture :
\nUne mise à jour typique des dépendances de package.json ressemble à ceci :
{
\"dependencies\": {
// upgrade to Docusaurus v3
- \"@docusaurus/core\": \"2.4.3\",
- \"@docusaurus/preset-classic\": \"2.4.3\",
+ \"@docusaurus/core\": \"3.0.0\",
+ \"@docusaurus/preset-classic\": \"3.0.0\",
// upgrade to MDX v3
- \"@mdx-js/react\": \"^1.6.22\",
+ \"@mdx-js/react\": \"^3.0.0\",
// upgrade to prism-react-renderer v2.0+
- \"prism-react-renderer\": \"^1.3.5\",
+ \"prism-react-renderer\": \"^2.1.0\",
// upgrade to React v18.0+
- \"react\": \"^17.0.2\",
- \"react-dom\": \"^17.0.2\"
+ \"react\": \"^18.2.0\",
+ \"react-dom\": \"^18.2.0\"
},
\"devDependencies\": {
// upgrade Docusaurus dev dependencies to v3
- \"@docusaurus/module-type-aliases\": \"2.4.3\",
- \"@docusaurus/types\": \"2.4.3\"
+ \"@docusaurus/module-type-aliases\": \"3.0.0\",
+ \"@docusaurus/types\": \"3.0.0\"
}
\"engines\": {
// require Node.js 18.0+
- \"node\": \">=16.14\"
+ \"node\": \">=18.0\"
}
}
A l'exception de MDX v3, la plupart des changements de rupture provenant de ces dépendances, qui ont été mises à jour, ont été gérés en interne pour vous : la plupart du temps, vous ne devriez pas avoir à faire quoi que ce soit. En dehors des dépendances, les seuls changements de rupture fonctionnels provenant explicitement de la base de code de Docusaurus sont les suivantes :
\n:::warning, supprime :::cautionv2.0.0-beta.10 (décembre 2021)Voici une liste non exhaustive des nouvelles fonctionnalités utiles de cette nouvelle version. Toutes les fonctionnalités sont listées dans les notes de version de Docusaurus v3.0.0.
\nDocusaurus v3 met à jour MDX v1 en MDX v3 :
\nCette nouvelle version de MDX est bien meilleure pour les rédacteurs de contenu et les auteurs de plugins, et prépare le terrain pour l'implémentation de nouvelles fonctionnalités Markdown passionnantes.
\nLa transition de MDX v1 à MDX v3 est le principal défi pour le passage à Docusaurus v3.
Certains documents qui ont été compilés avec succès sous Docusaurus v2 peuvent maintenant ne pas être compilés sous Docusaurus v3, tandis que d'autres peuvent s'afficher différemment.
La plupart des changements de rupture proviennent de [MDX v2(https://mdxjs.com/blog/v2/), et [MDX v3(https://mdxjs.com/blog/v3/) qui est une version relativement petite. Le guide de migration MDX v2 contient une section sur la façon de mettre à jour les fichiers MDX qui sera particulièrement pertinente pour nous. Assurez-vous également de lire la page Troubleshooting MDX qui peut vous aider à interpréter les messages d'erreur MDX les plus courants.
Ne soyez pas intimidé. La plupart des problèmes sont faciles à résoudre et souvent liés aux caractères { et < que vous devez maintenant échapper. Cependant, en fonction de la taille de votre site, vous pourriez avoir besoin de modifier de nombreux fichiers et vous sentir submergé. Pour cette raison, nous fournissons une commande npx docusaurus-mdx-checker pour vous aider à obtenir une estimation du travail à effectuer, et nous recommandons de préparer votre site à l'avance.
Si vous avez créé des plugins MDX (Remark/Rehype), l'AST est légèrement différent et vous devrez peut-être les refactoriser.
Cela nous permet notamment d'ajouter un mode CommonMark qui devrait faciliter l'adoption de Docusaurus pour les documentations existantes. Elle est actuellement facultative, expérimentale et limitée (certaines fonctionnalités de Docusaurus ne fonctionneront pas). Dans Docusaurus v3, tous les fichiers sont encore interprétés en MDX, mais nous prévoyons d'interpréter les fichiers .md en CommonMark dans une prochaine version majeure, et nous recommandons d'utiliser l'extension .mdx pour tout fichier utilisant les modules JSX ou ES.
Nous avons également introduit une nouvelle façon de configurer le Markdown globalement pour votre site, et nous prévoyons d'ajouter des options plus flexibles ultérieurement.
\nexport default {
markdown: {
format: 'mdx',
mermaid: true,
preprocessor: ({filePath, fileContent}) => {
return fileContent.replaceAll('{{MY_VAR}}', 'MY_VALUE');
},
mdx1Compat: {
comments: true,
admonitions: true,
headingIds: true,
},
},
};
Docusaurus utilise désormais le plugin remark-directive pour prendre en charge les admonitions. Cela vous offre également la possibilité de créer vos propres plugins Remark pour étendre Markdown avec vos propres directives personnalisées telles que :textDirective, ::leafDirective ou :::containerDirective.
Dans #9317, nous avons ajouté la prise en charge des modules ES et des fichiers de config TypeScript, y compris la config du site, les barres latérales des docs, les plugins et les presets.
\nVoici 2 exemples TypeScript, vous donnant une expérience moderne avec l'autocomplétion de l'IDE :
\nimport type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';
const config: Config = {
title: 'Mon Site',
favicon: 'img/favicon.ico',
// Votre config de site ...
presets: [
[
'classic',
{
// Votre config de preset ...
} satisfies Preset.Options,
],
],
themeConfig: {
// Votre config de thème ...
} satisfies Preset.ThemeConfig,
};
export default config;
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
const sidebars: SidebarsConfig = {
docs: ['introduction'],
};
export default sidebars;
Docusaurus prenait déjà en charge l'option draft : true dans nos 3 plugins de contenu (docs, blog, pages), ce qui vous permet de supprimer certaines pages de vos versions de production.
Dans #8004, nous avons introduit une nouvelle option unlisted : true, qui gardera vos pages disponibles dans les constructions de production, tout en les « cachant » et en les rendant impossibles à découvrir à moins que vous n'ayez l'url. Cela permet de mettre en place des flux de travail utiles où vous pouvez facilement demander un avis sur un élément de contenu avant la publication finale.
Le contenu non listé sera :
\nsitemap.xml<meta name=\"robots\" content=\"noindex, nofollow\" />Les contenus non listés affichent également une bannière afin que vous n'oubliiez pas de la désactiver une fois que votre contenu est prêt pour le grand jour. Voici un exemple d'article du blog non listé :
\nDans #8961, nous avons fait la mise à jour vers React 18. C'est important, notamment pour l'adoption progressive des fonctionnalités Concurrent de React, ainsi que pour les fonctionnalités prometteuses à venir telles que les composants de serveur React à l'exécution de la construction.
\nCette nouvelle version de React devrait pouvoir remplacer la plupart des sites Docusaurus. Elle s'accompagne de changements de rupture que nous avons gérés en interne dans la base de code de Docusaurus. Si votre site utilise beaucoup de code React personnalisé, nous vous recommandons de consulter l'article officiel sur Comment passer à React 18, notamment le nouveau comportement de batching automatique.
\nReact 18 est livré avec de nouvelles fonctionnalités :
<Suspense>React.lazy()startTransition()Leur prise en charge par Docusaurus est considérée comme expérimentale. Nous pourrions être amenés à ajuster l'intégration à l'avenir, ce qui entraînerait un comportement différent au niveau de l'exécution.
Docusaurus v3 utilise désormais le runtime JSX « automatique ».
\nIl n'est plus nécessaire d'importer React dans les fichiers JSX qui n'utilisent aucune API React.
\n- import React from 'react';
export default function MyComponent() {
return <div>Hello</div>;
}
Il est maintenant possible de construire votre site statique en mode dev.
\ndocusaurus build --dev
Docusaurus enregistrera plus d'erreurs dans la console, notamment les erreurs d'hydratation de React 18 grâce au nouveau callback onRecoverableError.
Ce nouveau mode de compilation est particulièrement utile pour résoudre les problèmes de React. Docusaurus utilisera la version de développement de React, produisant ainsi des messages d'erreur détaillés et lisibles au lieu de messages minifiés renvoyant à la page du décodeur d'erreurs React.
Docusaurus v3 nécessite maintenant une version minimale de TypeScript 5.0.
\nNous avons réinternalisé la config TypeScript de base recommandée dans un nouveau package officiel :
\n {
- \"extends\": \"@tsconfig/docusaurus/tsconfig.json\",
+ \"extends\": \"@docusaurus/tsconfig\",
\"compilerOptions\": {
\"baseUrl\": \".\"
}
}
Nous avons également des exportations plus propres et normalisées pour le type du noyau de Docusaurus, les plugins et les options de preset, que vous pouvez utiliser dans les tous nouveaux fichiers de configuration TypeScript :
\nimport type {Config} from '@docusaurus/types';
import type {Options, ThemeConfig} from '@docusaurus/preset-classic';
import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
Dans #9316, nous avons amélioré la coloration syntaxique grâce à la mise à jour de prism-react-renderer v2. Par exemple, le paramètre bash --save est maintenant colorisé :
npm install --save some-package
L'éditeur de code interactif passe également à react-live v4, avec un nouveau compilateur sucrase. Il est plus rapide, plus léger et prend en charge des fonctionnalités modernes, notamment les annotations de type TypeScript.
\nfunction Hello() {\n const name: string = 'World';\n return <div>Hello {name}</div>;\n}\n
Dans #8982 et #8870, nous avons également ajouté la prise en charge des commentaires magiques pour les syntaxes de commentaires de type TeX, Haskell et WebAssembly.
\nstringLength :: String -> Int
stringLength [] = 0
stringLength (x:xs) = 1 + stringLength xs
function result = times2(n)
result = n * 2;
end
x = 10;
y = times2(x);
Dans #9305, nous avons mis à jour Mermaid v10.4 et ajouté la prise en charge du rendu asynchrone des diagrammes. Docusaurus est maintenant en mesure de rendre de nouveaux types de diagrammes.
\nDans #9028, nous avons rendu possible la définition d'attributs de données HTML personnalisés à travers les paramètres de la chaîne de requête docusaurus-data-x. Cela facilite l'intégration d'un iframe Docusaurus sur un autre site et vous permet de personnaliser l'apparence de la version intégrée à l'aide de CSS.
html[data-navbar='false'] .navbar {
display: none;
}
html[data-red-border] div#__docusaurus {
border: red solid thick;
}
Autres nouvelles fonctionnalités à mentionner :
\nfeedOptions.limitno-html-linksprefer-docusaurus-headingConsultez les notes de version de Docusaurus v3.0.0 pour une liste exhaustive des changements.
\nCette version est fournie avec quelques fonctionnalités, mais plus important encore, met à jour de nombreuses pièces de l'infrastructure Docusaurus.
\nLa mise à jour MDX a consommé beaucoup de notre temps cette année, et nous avons travaillé dur pour rendre cette importante mise à jour moins difficile pour vous tous.
\nMaintenant que nous avons rattrapé notre retard en matière d'infrastructure, nous serons de retour pour délivrer des fonctionnalités de documentation utiles très bientôt, dans les prochaines versions mineures.
\nNous vous remercions d'utiliser Docusaurus au fil des ans. Le marché des frameworks de documentation devient de plus en plus concurrentiel ces derniers temps, et nous ferons de notre mieux pour que Docusaurus reste une solution compétitive qui se distingue par sa grande flexibilité.
", "url": "https://docusaurus.io/fr/blog/releases/3.0", "title": "Annonce de Docusaurus 3.0", "summary": "Aujourd'hui, nous sommes heureux d'annoncer Docusaurus 3.0 ! 🥳", "date_modified": "2023-10-31T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/preparing-your-site-for-docusaurus-v3", "content_html": "This blog post was written when Docusaurus v3 was in beta. There are some changes in dependency versions and upgrade steps you should be aware of if upgrading to Docusaurus v3 current stable releases. Use the upgrade guide for the most up-to-date migration steps.
Docusaurus v3 est maintenant en beta et la sortie officielle est imminente. C'est le moment idéal pour commencer à préparer votre site pour cette nouvelle version majeure.
\nDocusaurus v3 comporte quelques changements de rupture, dont beaucoup peuvent être traités aujourd'hui avec Docusaurus v2. La préparation de votre site en amont peut se faire de manière progressive et facilitera la mise à niveau vers la v3.
\nLe principal changement de rupture est la mise à jour de MDX v1 vers MDX v3. Lisez les notes de version pour MDX v2 et MDX v3 pour plus de détails. MDX compile maintenant votre contenu Markdown plus strictement et avec des différences subtiles.
\nCet article se concentrera principalement sur la façon de préparer votre contenu pour cette nouvelle version de MDX, et énumérera également quelques autres changements de rupture que vous pouvez traiter dès aujourd'hui.
\n![\"Préparation](\"https://docusaurus.io/fr/assets/images/social-card-1c688c53b51bdaa6e15ae532bf756276.png\")
Cet article mentionne la plupart des changements de rupture de Docusaurus v3, mais ce n'est pas exhaustif. Lisez la v3.0.0-beta.0 release notes pour une liste exhaustive.
Il y a beaucoup de contenu dans cet article du blog, mais de nombreux sites Docusaurus v2 peuvent être mis à jour avec très peu de changements.
Si votre site est relativement petit, avec seulement quelques personnalisations, vous pouvez probablement passer à Docusaurus v3 immédiatement.
Avant de préparer la mise à niveau de Docusaurus v3, nous vous recommandons d'effectuer une mise à niveau vers la dernière version de Docusaurus v2.
\nEn fonction de la complexité de votre site, il peut être judicieux d'adopter le flux de travail des tests de régression visuels que nous avons récemment présenté. Cela pourrait vous aider à détecter des effets secondaires visuels inattendus survenant lors de la mise à jour de Docusaurus v3.
\nNous recommandons également d'utiliser l'extension .mdx chaque fois que vous utilisez JSX, import, ou export (par exemple les fonctionnalités MDX) dans un fichier Markdown. Elle est plus correcte sémantiquement et améliore la compatibilité avec les outils externes (IDE, formateurs, linters, etc.). Dans les versions futures de Docusaurus, les fichiers .md seront analysés comme du CommonMark standard, qui ne prend pas en charge ces fonctionnalités. Dans Docusaurus v3, les fichiers .md continuent d'être compilés comme des fichiers MDX, mais il sera possible d'opter pour CommonMark.
MDX est une dépendance majeure de Docusaurus responsable de la compilation de vos fichiers .md et .mdx en composants React.
MDX v3 est bien meilleur, mais s'accompagne également de changements qui vous obligeront probablement à remanier quelque peu votre contenu. MDX v3 est plus strict, et certains composants qui se compilaient bien sous v1 peuvent maintenant ne pas se compiler sous v2, très probablement à cause des caractères { et <.
La mise à jour de MDX s'accompagne de toutes les changements de rupture documentés dans les articles du blog sur les versions MDX v2 et MDX v3. Les changements de rupture les plus importants proviennent de MDX v2. Le guide de migration MDX v2 contient une section sur la façon de mettre à jour les fichiers MDX qui sera particulièrement pertinente pour nous. Assurez-vous également de lire la page Troubleshooting MDX qui peut vous aider à interpréter les messages d'erreur MDX les plus courants.
\nVeillez également à lire notre page de documentation actualisée de MDX et React.
\nNous avons une discussion dédiée à MDX v3 - Support de mise à jour.
Le terrain de jeu du MDX est votre nouveau meilleur ami. Il permet de comprendre comment votre contenu est compilé en composants React, et de résoudre les problèmes de compilation ou de rendu de manière isolée.
\nChaque version MDX est livrée avec son propre terrain de jeu :
\n\nPour obtenir un comportement de compilation similaire à celui de Docusaurus v2, activez ces options sur le terrain de jeu MDX :
MDXremark-gfmremark-directive![\"Capture](\"https://docusaurus.io/fr/assets/images/mdx2-playground-options-eab88e8328a6902759c4236ffc93d9c6.png\")
En utilisant les deux terrains de jeu MDX côte à côte, vous remarquerez rapidement que certains contenus sont compilés différemment ou ne se compilent pas dans la v3.
\nL'objectif est de remanier votre contenu problématique afin qu'il fonctionne correctement avec les deux versions du MDX. Ainsi, lorsque vous passerez à Docusaurus v3, ce contenu sera déjà prêt à l'emploi.
Nous fournissons un CLI docusaurus-mdx-checker qui permet de repérer facilement les contenus problématiques. Exécutez cette commande aujourd'hui sur votre site Docusaurus v2 pour obtenir la liste des fichiers qui ne pourront pas être compilés sous MDX v3.
\nnpx docusaurus-mdx-checker
Pour chaque problème de compilation, le CLI enregistre le chemin d'accès au fichier et un numéro de ligne à consulter.
\n![\"Capture](\"https://docusaurus.io/fr/assets/images/mdx-checker-output-0f96cc19fd3ed4d55901ca90ad657c14.png\")
Utilisez ce CLI pour estimer la quantité de travail nécessaire pour rendre votre contenu compatible avec MDX v3.
Ce CLI est le fruit de notre travail et ne signale que les erreurs de compilation.
Il ne signale pas les modifications subtiles de la compilation qui ne produisent pas d'erreurs mais qui peuvent affecter l'affichage de votre contenu. Pour détecter ces problèmes, nous recommandons d'utiliser des tests de régression visuels.
Nous avons mis à jour quelques sites Docusaurus vers Docusaurus v3 et MDX v3 :
\n\nCes mises à jour nous ont permis de regrouper les problèmes de contenu les plus courants et de documenter la meilleure façon de les traiter.
\n{Le caractère { est utilisé pour ouvrir des expressions JavaScript. Désormais, MDX échouera si ce que vous mettez dans {expression} n'est pas une expression valide.
La forme de l'objet ressemble à {username: string, age: number}
\nCould not parse expression with acorn: Unexpected content after expression
\n
Options disponibles pour corriger cette erreur :
{username: string, age: number}{\\{<Le caractère < est utilisé pour ouvrir des balises JSX. Désormais, MDX échouera s'il pense que votre JSX n'est pas valide.
Utiliser la version Android <5
Vous pouvez utiliser un type générique comme Array<T>
Suivez le modèle \"Road to <YOUR_MINOR_VERSION>\"
\nUnexpected character
\n5(U+0035) before name, expected a character that can start a name, such as a letter,$, or_Expected a closing tag for
\n<T>(1:6-1:9) before the end ofparagraphend-tag-mismatch mdast-util-mdx-jsxExpected a closing tag for
\n<YOUR_MINOR_VERSION>(134:19-134:39) before the end ofparagraph
Options disponibles pour corriger cette erreur :
Array<T>&lt; ou <\\< (malheureusement le \\ sera affiché sous MDX v1)Docusaurus prend en charge GitHub Flavored Markdown (GFM), mais autolink utilisant la syntaxe <link> n'est plus pris en charge par MDX.
<sebastien@thisweekinreact.com>
<http://localhost:3000>
\nUnexpected character
\n@(U+0040) in name, expected a name character such as letters, digits,$, or_; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use[text](url))Unexpected character
\n/(U+002F) before local name, expected a character that can start a name, such as a letter,$, or_(note: to create a link in MDX, use[text](url))
Utilisez des liens Markdown classiques, ou supprimez les < et >. MDX et GFM sont déjà en mesure d'établir des liens automatiques avec les littéraux.
sebastien@thisweekinreact.com
[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)
http://localhost:3000
[http://localhost:3000](http://localhost:3000)
Pour les utilisateurs fournissant une correspondance MDXComponent personnalisée, les composants sont maintenant « mis en bac à sable » :
MDXComponent pour h1 n'est utilisée que pour # hi mais pas pour <h1>hi</h1>MDXComponent respectifVotre correspondance de composant MDXComponent pourrait ne pas être appliquée comme avant, et vos composants personnalisés pourraient ne plus être utilisés.
Pour les éléments Markdown natifs, vous pouvez continuer à utiliser les minuscules : p, h1, img, a...
Pour tout autre élément, utiliser des noms en majuscules.
import MDXComponents from '@theme-original/MDXComponents';
export default {
...MDXComponents,
p: (props) => <p {...props} className=\"my-paragraph\"/>
- myElement: (props) => <div {...props} className=\"my-class\" />,
+ MyElement: (props) => <div {...props} className=\"my-class\" />,
};
Dans MDX v3, il est désormais possible d'intercaler du JSX et du Markdown plus facilement sans avoir besoin de sauts de ligne supplémentaires. L'écriture d'un contenu sur plusieurs lignes peut également produire de nouvelles balises <p> attendues.
Voyez comment ce contenu est rendu différemment par MDX v1 et v3.
<div>Un peu de contenu **Markdown**</div>
<div>
Un peu de contenu **Markdown**
</div>
<div>Un peu de contenu **Markdown**</div>
<div>Un peu de contenu **Markdown**</div>
<div>Un peu de contenu <strong>Markdown</strong></div>
<div><p>Un peu de contenu <strong>Markdown</strong></p></div>
Si vous ne voulez pas de balise <p> supplémentaire, remaniez le contenu au cas par cas pour utiliser une balise JSX sur une seule ligne.
<figure>
<img src=\"/img/myImage.png\" alt=\"My alt\" />
- <figcaption>
- Légende de mon image
- </figcaption>
+ <figcaption>Légende de mon image</figcaption>
</figure>
Si votre contenu contient des « Markdown en ligne » (**, *, _, [link](/path)), il se peut que vous ne puissiez pas le remanier à l'avance, et devrez le faire en même temps que la mise à jour de Docusaurus v3.
Docusaurus v3 utilise désormais des directives Markdown (mises en œuvre avec remark-directive) comme moyen générique de fournir un support pour les admonitions, et d'autres fonctionnalités à venir de Docusaurus.
\nCeci est un :texteDeDirective
::directiveFeuille
:::conteneurDeDirective
Contenu du conteneur de la directive
:::
Les directives sont analysées dans le but d'être traitées par d'autres plugins Remark. Les directives non traitées seront ignorées et ne seront pas restituées dans leur forme originale.
La conférence AWS re:Invent est formidable
En raison de l'analyse de :Invent en tant que directive de texte, ceci sera maintenant rendu ainsi :
La conférence AWS re
est formidable
:: (si cela a du sens) : : texte\\: (malheureusement le \\ sera affiché sous MDX v1)MDX ne transforme plus le texte indenté comme des blocs de code.
\n console.log(\"hello\");
La mise à jour ne produit généralement pas de nouvelles erreurs de compilation MDX, mais peut entraîner un rendu inattendu du contenu parce qu'il n'y a plus de bloc de code.
Utilisez la syntaxe du bloc de code normal au lieu de l'indentation :
```js
console.log('hello');
```
Tous les paquets officiels (Unified, Remark, Rehype...) dans l'écosystème MDX sont désormais des Modules ES uniquement et ne supportent plus [CommonJS] (https://nodejs.org/api/modules.html#modules-commonjs-modules).
\nEn pratique, cela signifie que vous ne pouvez plus faire de require(\"remark-plugin\").
Docusaurus v3 prend désormais en charge les fichiers de configuration ES Modules. Nous vous recommandons de migrer votre fichier de config vers le ES module, qui vous permet d'importer facilement les plugins Remark :
import remarkPlugin from 'remark-plugin';
export default {
title: 'Docusaurus',
/* config du site à l'aide des plugins remark ici */
};
Si vous souhaitez continuer à utiliser les modules CommonJS, vous pouvez utiliser les importations dynamiques comme solution de contournement qui vous permet d'importer des modules ES à l'intérieur d'un module CommonJS. Heureusement, la config de Docusaurus prend en charge l'utilisation d'une fonction asynchrone qui vous permet de le faire.
module.exports = async function () {
const myPlugin = (await import('remark-plugin')).default;
return {
// config du site...
};
};
Si vous avez créé des plugins Remark ou Rehype personnalisés, vous devrez peut-être les refactoriser, voire les réécrire complètement, étant donné la façon dont le nouveau système AST est structuré. Nous avons créé une discussion d'assistance dédiée pour aider les auteurs de plugins à mettre à jour leur code.
Hormis le MDX, il existe d'autres changements de rupture auxquels vous pouvez d'ores et déjà préparer votre site, notamment des montées de version majeures de dépendances importantes.
\nNode.js 16 a atteint sa fin de vie, et Docusaurus v3 nécessite désormais Node.js >= 18.0.
\nVeuillez mettre à jour votre site Docusaurus v2 vers Node.js 18 avant de passer à Docusaurus v3.
Docusaurus v3 nécessite désormais React >= 18.0.
\nReact 18 s'accompagne de ses propres changements de rupture qui devraient être relativement faciles à gérer, selon la quantité de code React personnalisé que vous avez créé pour votre site.
\nLes simples sites Docusaurus, qui n'utilisent que du code de notre thème officiel sans swizzling, n'ont aucun souci à se faire.
\nLisez les documents officiels de React v18.0 et Comment passer à React 18, et examinez votre code React initial pour déterminer les composants susceptibles d'être affectés par cette mise à niveau de React 18.
Nous recommandons de vérifier tout particulièrement les points suivants :
Docusaurus v3 nécessite désormais TypeScript >= 5.0.
\nVeuillez mettre à jour votre site Docusaurus v2 vers TypeScript 5 avant de passer à Docusaurus v3.
La configuration officielle de TypeScript de Docusaurus a été réinternalisée depuis le paquet externe @tsconfig/docusaurus vers notre nouveau paquet monorepo @docusaurus/tsconfig.
Ce nouveau paquet est versionné en même temps que tous les autres paquets de base de Docusaurus, et il sera utilisé pour assurer la rétro-compatibilité de TypeScript et les changements de rupture lors des mises à jour de versions majeures.
\nLa nouvelle configuration TypeScript de Docusaurus v3 est judicieusement la même que l'ancienne configuration TypeScript de Docusaurus v2. Si vous avez effectué la montée de version vers TypeScript 5, l'utilisation de la configuration de Docusaurus v3 sur un site v2 est déjà possible :
{
\"devDependencies\": {
- \"@tsconfig/docusaurus\": \"^1.0.7\",
+ \"@docusaurus/tsconfig\": \"^3.0.0-beta.0\",
}
}
{
- \"extends\": \"@tsconfig/docusaurus/tsconfig.json\",
+ \"extends\": \"@docusaurus/tsconfig\",
\"compilerOptions\": {
\"baseUrl\": \".\"
}
}
Pour des raisons historiques, nous prenons en charge un admonition non documenté :::warning qui s'affiche avec une couleur rouge.
Ceci est une admonition de Docusaurus v2 :::warning.
Cependant, la couleur et l'icône sont historiquement erronées. Docusaurus v3 réintroduit officiellement l'admonition :::warning, la documente, et corrige la couleur et l'icône.
Ceci est une admonition de Docusaurus v3 :::warning.
Si vous utilisiez auparavant l'admonition non documentées :::warning, vérifiez pour chaque utilisation si le jaune est maintenant une couleur appropriée. Si vous voulez conserver la couleur rouge, utilisez :::danger à la place.
Docusaurus v3 a aussi déprécié l'admonition :::caution. Veuillez refactoriser :::caution (jaune) soit en :::warning (jaune) soit en :::danger (rouge).
Ce changement de rupture n'affectera que les utilisateurs de Docusaurus v2 qui ont versionné leurs documents avant la v2.0.0-beta.10 (décembre 2021).
Lors de la création de la version v1.0.0, le fichier sidebar contenait un préfixe version-v1.0.0/ que Docusaurus v3 ne prend plus en charge.
{
\"version-v1.0.0/docs\": [
\"version-v1.0.0/introduction\",
\"version-v1.0.0/prerequisites\"
]
}
Votre site Docusaurus v2 est capable de gérer les deux formats de barres latérales de la même manière.
Vous pouvez supprimer le préfixe versionné inutile de vos barres latérales versionnées.
{
\"docs\": [\"introduction\", \"prerequisites\"]
}
Docusaurus v3 est maintenant en beta, et déjà utilisé en production par React-Native, Jest et notre propre site web.
\nNous pensons que cette nouvelle version de Docusaurus est robuste et prête à être déployée en production. Il devrait être lancé officiellement bientôt, après avoir reçu un retour positif de la part des premiers utilisateurs de notre communauté.
\nNous vous serions très reconnaissants d'essayer la mise à jour et de signaler les problèmes sur le fil de discussion sur la version 3.0.0-beta.0.
\nPour la plupart des sites, la mise à jour devrait être facile. Si vous avez préparé votre site au préalable comme indiqué ici, la mise à jour des dépendances suivantes devrait suffire :
\n {
\"dependencies\": {
- \"@docusaurus/core\": \"2.4.3\",
- \"@docusaurus/preset-classic\": \"2.4.3\",
- \"@mdx-js/react\": \"^1.6.22\",
+ \"@docusaurus/core\": \"3.0.0-beta.0\",
+ \"@docusaurus/preset-classic\": \"3.0.0-beta.0\",
+ \"@mdx-js/react\": \"^3.0.0\",
\"clsx\": \"^2.0.0\",
\"prism-react-renderer\": \"^1.3.5\",
- \"react\": \"^17.0.2\",
- \"react-dom\": \"^17.0.2\"
+ \"react\": \"^18.2.0\",
+ \"react-dom\": \"^18.2.0\"
},
\"devDependencies\": {
- \"@docusaurus/module-type-aliases\": \"2.4.3\"
+ \"@docusaurus/module-type-aliases\": \"3.0.0-beta.0\"
}
}
Nous serons là pour vous aider à effectuer la montée de version par le biais des canaux d'assistance suivants :
\nVous pouvez également faire appel à un fournisseur de service Docusaurus payant pour effectuer cette montée de version à votre place. Si votre site est open source, vous pouvez également demander à notre communauté une aide gratuite et bienveillante.
\nDocusaurus v3 est prêt à être essayé, et sera bientôt disponible. Cet article vous donne déjà une bonne idée de tous les changements majeurs nécessaires à la montée de version.
\nLa version initiale 3.0 se concentre sur les dépendances et les mises à niveau de l'infrastructure qui nous permettront d'implémenter de nouvelles fonctionnalités intéressantes. Elle est également dotée de quelques fonctionnalités utiles que nous détaillerons dans les notes de la version finale.
", "url": "https://docusaurus.io/fr/blog/preparing-your-site-for-docusaurus-v3", "title": "Préparation de votre site pour Docusaurus v3", "summary": "This blog post was written when Docusaurus v3 was in beta. There are some changes in dependency versions and upgrade steps you should be aware of if upgrading to Docusaurus v3 current stable releases. Use the upgrade guide for the most up-to-date migration steps.", "date_modified": "2023-09-29T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "Maintenance" ] }, { "id": "https://docusaurus.io/fr/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing", "content_html": "Les développeurs frontend ont souvent besoin de mettre à jour les dépendances npm, mais ces mises à jour peuvent être angoissantes et entraîner des effets secondaires subtils sur l'interface utilisateur qui ne sont pas détectés par votre suite de tests habituelle.
\nLa mise à jour de Docusaurus est un bon exemple : à moins de revoir toutes les pages une à une, il est difficile de s'assurer qu'il n'y a pas de régression visuelle. Docusaurus v3 est sur le point de sortir (actuellement en beta), et nous aimerions vous aider à effectuer cette mise à jour en toute confiance.
\nCet article présente un flux de travail de test sur la régression visuelle basé sur GitHub Actions, Playwright et Argos. Il n'est pas directement lié à Docusaurus ou React, et peut être adapté pour fonctionner avec d'autres applications frontend et d'autres frameworks.
\n![\"Mettre](\"https://docusaurus.io/fr/assets/images/social-card-0662a6f419d0032829f99915ccf8918b.png\")
Ce flux de travail a été testé lors de la montée de version de Docusaurus v2 vers v3, et a déjà permis de corriger quelques régressions visuelles sur des sites tels que React Native, Jest, et le site Docusaurus lui-même.
\nDocusaurus v3 s'accompagne de changements d'infrastructure et de mises à niveau de dépendances majeures telles que MDX v3 et React 18, qui peuvent produire des effets secondaires inattendus. Il aurait été difficile de constater toutes les régressions visuelles en l'absence d'un tel flux de travail. C'est pourquoi nous encourageons les propriétaires de sites à adopter des tests de régression visuels, en particulier pour les sites hautement personnalisés.
\nL'idée générale est assez simple :
\nsitemap.xml avec Playwrightmain et pr-branch.Argos va alors signaler les différences visuelles trouvées entre main et pr-branch sous forme d'un statut de commit GitHub et d'un commentaire de pull-request. Cela peut vous aider à détecter les régressions visuelles en amont de manière automatisée.
![\"Statut](\"https://docusaurus.io/fr/assets/images/argos-github-status-05e8264c59fa4f8a21292f59665edf3d.png\")
![\"Commentaire](\"https://docusaurus.io/fr/assets/images/argos-github-comment-8b62a1561b13881608d5c9f8a8f833a5.png\")
Argos crée un rapport référençant toutes les différences visuelles trouvées en comparant l'un à l'autre les sites des 2 branches Git, et fournit une interface utilisateur pratique pour repérer facilement la différence.
\nConsultez la page Argos de Docusaurus pour explorer les rapports de notre propre site web.
\nVoici un exemple plus concret d'Argos signalant une régression visuelle trouvé lors de la mise à jour du site web React-Native :
\n![\"Commentaire](\"https://docusaurus.io/fr/assets/images/argos-react-native-regression-216ace77baedfaf873a770112ec817ac.png\")
Cette section décrit les modalités de mise en place de chaque étape du flux de travail.
\nVous devrez vous inscrire à Argos et connecter Argos à votre dépôt GitHub
\nCe flux de travail nécessite les dépendances suivantes, en plus des dépendances habituelles de Docusaurus :
\nyarn add -D @argos-ci/cli @argos-ci/playwright @playwright/test cheerio
GitHub action se charge de l'exécution du flux de travail pour chaque branche Git.
\nUn flux de travail minimal pourrait ressembler à ce qui suit :
\nname: Argos CI Screenshots
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
take-screenshots:
runs-on: ubuntu-latest
steps:
- name: Check out repository code
uses: actions/checkout@v4
- name: Use Node.js
uses: actions/setup-node@v3
with:
node-version: current
- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Install Playwright browsers
run: yarn playwright install --with-deps chromium
- name: Build the website
run: yarn docusaurus build
- name: Take screenshots with Playwright
run: yarn playwright test
- name: Upload screenshots to Argos
run: yarn argos upload ./screenshots
Playwright se charge des captures d'écran du site web précédemment construit localement par Github action.
\nUne config de Playwright minimale pourrait ressembler à ce qui suit :
\nimport {devices} from '@playwright/test';
import type {PlaywrightTestConfig} from '@playwright/test';
const config: PlaywrightTestConfig = {
webServer: {
port: 3000,
command: 'yarn docusaurus serve',
},
projects: [
{
name: 'chromium',
use: {
...devices['Desktop Chrome'],
},
},
],
};
export default config;
Une config de Playwright ne suffit pas : nous devons également écrire un fichier de test Playwright pour générer les captures d'écran du site.
\nimport * as fs from 'fs';
import {test} from '@playwright/test';
import {argosScreenshot} from '@argos-ci/playwright';
import {extractSitemapPathnames, pathnameToArgosName} from './utils';
// Constantes
const siteUrl = 'http://localhost:3000';
const sitemapPath = './build/sitemap.xml';
const stylesheetPath = './screenshot.css';
const stylesheet = fs.readFileSync(stylesheetPath).toString();
// Attends l'hydratation, nécessite Docusaurus v2.4.3+
// Docusaurus ajoute un <html data-has-hydrated=\"true\"> une fois l'hydratation terminée
// Consultez https://github.com/facebook/docusaurus/pull/9256
function waitForDocusaurusHydration() {
return document.documentElement.dataset.hasHydrated === 'true';
}
function screenshotPathname(pathname: string) {
test(`pathname ${pathname}`, async ({page}) => {
const url = siteUrl + pathname;
await page.goto(url);
await page.waitForFunction(waitForDocusaurusHydration);
await page.addStyleTag({content: stylesheet});
await argosScreenshot(page, pathnameToArgosName(pathname));
});
}
test.describe('Docusaurus site screenshots', () => {
const pathnames = extractSitemapPathnames(sitemapPath);
console.log('Pathnames to screenshot:', pathnames);
pathnames.forEach(screenshotPathname);
});
Argos dispose d'une intégration Playwright qui reprend l'API originale de capture d'écran Playwright et fournit de meilleures valeurs par défaut pour rendre les captures d'écran suffisamment détaillées.
utils.ts ?Ce module contient des détails d'implémentation que nous avons choisi de masquer par souci de clarté.
import * as cheerio from 'cheerio';
import * as fs from 'fs';
// Extrait une liste de noms de chemin, à partir d'un chemin fs vers un fichier sitemap.xml
// Docusaurus génère un fichier build/sitemap.xml pour vous !
export function extractSitemapPathnames(sitemapPath: string): string[] {
const sitemap = fs.readFileSync(sitemapPath).toString();
const $ = cheerio.load(sitemap, {xmlMode: true});
const urls: string[] = [];
$('loc').each(function handleLoc() {
urls.push($(this).text());
});
return urls.map((url) => new URL(url).pathname);
}
// Convertit un nom de chemin en un nom de capture d'écran convenable
export function pathnameToArgosName(pathname: string): string {
return pathname.replace(/^\\/|\\/$/g, '') || 'index';
}
Les captures d'écran ne sont pas toujours suffisamment détaillées, et le fait de prendre deux fois une capture d'écran d'une page peut entraîner des variations subtiles qui seront signalées de manière incorrecte par Argos comme des régressions visuelles.
\nC'est pourquoi nous recommandons d'injecter une feuille de style supplémentaire pour masquer les éléments problématiques. Vous devrez probablement ajouter de nouvelles règles CSS à cette feuille de style de base, en fonction des éléments instables trouvés sur votre propre site. Consultez Argos - Docs à propos des tests instables pour plus d'informations.
\n/* Les iframes peuvent se charger de manière différée */
iframe,
/* Les avatars peuvent être instables en raison de l'utilisation de sources externes : GitHub/Unavatar */
.avatar__photo,
/* Les Gif se chargent de manière différée et sont animés */
img[src$='.gif'],
/* Les raccourcis clavier d'Algolia apparaissent avec un peu de retard */
.DocSearch-Button-Keys > kbd,
/* L'aperçu de l'aire de jeu en direct peut souvent afficher des dates/compteurs */
[class*='playgroundPreview'] {
visibility: hidden;
}
/* Différentes dates de dernière mise à jour des documents peuvent modifier la mise en page */
.theme-last-updated,
/* Les diagrammes Mermaid sont rendus côté client et produisent des changements de mise en page */
.docusaurus-mermaid-container {
display: none;
}
Nous recommandons de masquer les éléments instables de l'interface utilisateur qui affectent la mise en page avec display : none;.
Par exemple, la documentation « Dernière mise à jour le » peut être affichée sur plus d'une ligne, ce qui « pousse » le reste du contenu vers le bas et conduit Argos à détecter de nombreux pixels différents.
Le dépôt slorber/docusaurus-argos-example montre un exemple complet de mise en place de ce flux de travail sur un site Docusaurus v2 nouvellement initialisé, en utilisant un monorepo Yarn.
\n![\"Capture](\"https://docusaurus.io/fr/assets/images/docusaurus-argos-example-repo-screenshot-a56583e16aa02c7fa96c592f1339928f.png\")
Pull-requests significatives :
\nConsultez le dépôt de Docusaurus pour une intégration plus avancée :
Les outils que nous choisissons sont des éléments importants de la mise en place de ce flux de travail de test de régression visuel.
\nPour Docusaurus, nous avons choisi Argos : il fonctionne bien chez nous et propose des plans gratuits et open source. Toutefois, vous êtes libre d'adopter d'autres outils.
\nSi cela ne vous dérange pas de stocker de grandes captures d'écran dans Git, vous pouvez également essayer le logiciel gratuit et auto-hébergé Playwright Visual Comparisons et parcourir les différences visuelles avec npx playwright show-report. Cependant, nous avons constaté que l'utilisation d'un outil externe dédié est plus pratique.
Les outils externes peuvent être coûteux, mais ils offrent généralement des plans gratuits avec un quota important de captures d'écran. Vous pouvez réduire votre consommation de captures d'écran en appliquant les quelques astuces ci-dessous.
\nLa configuration de base consiste à faire une capture d'écran de chaque chemin trouvé dans sitemap.xml. Pour les sites de grande taille, cela peut se traduire par un grand nombre de captures d'écran.
Vous pouvez décider de filtrer les noms de chemin pour ne prendre que les captures d'écran des pages les plus critiques.
\nPour le site web Docusaurus, ne faites pas de captures d'écran pour les pages de docs versionnés :
\nfunction isVersionedDocsPathname(pathname: string): boolean {
return pathname.match(/^\\/docs\\/((\\d\\.\\d\\.\\d)|(next))\\//);
}
test.describe('Docusaurus site screenshots', () => {
const pathnames = extractSitemapPathnames(sitemapPath)
.filter(isVersionedDocsPathname);
pathnames.forEach(screenshotPathname);
});
La mise en place de groupes de simultanéité pour les GitHub Actions permet d'éviter que des commits successifs ne déclenchent de multiples exécutions inutiles de flux de travail. Le flux de travail ne sera exécuté que pour le dernier commit, et pour les commits précédents, ils seront automatiquement annulés.
\nconcurrency:
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
cancel-in-progress: true
Il n'est pas utile d'exécuter ce flux de travail pour chaque commit et chaque pull-request.
\nPar exemple, si quelqu'un corrige une coquille dans votre documentation, vous ne voudrez probablement pas prendre des centaines de captures d'écran et demander à Argos de signaler que seule la page modifiée présente une différence visuelle : bien sûr, c'est un peu attendu !
\nPour le site web de Docusaurus, nous n'exécutons le flux de travail que pour les pull-request ayant le label Argos :
name: Argos CI Screenshots
on:
push:
branches: [main]
pull_request:
branches: [main]
types:
- opened
- synchronize
- reopened
- labeled
jobs:
take-screenshots:
if: ${{ github.ref_name == 'main' || (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'Argos')) }}
runs-on: ubuntu-latest
steps:
# Vos étapes de travail ici ...
Il existe de nombreuses options à explorer, telles que déclencher le flux de travail manuellement ou uniquement lorsque les fichiers correspondant à un pattern spécifique sont modifiés.
\nJe pense que les tests de régression visuels sont sous-utilisés dans l'écosystème frontend.
\nLa réalisation de captures d'écran pleine page est à portée de main, elle est facile à mettre en place et peut vous aider à intercepter une nouvelle classe de bogues que votre suite de tests habituelle n'aurait pas détectée. Cette technique n'est pas seulement utile pour les mises à jour de paquets npm, mais aussi pour tout type de refactorisation qui ne doit pas changer l'interface utilisateur.
\nAlors pourquoi ne pas essayer ?
\nBon codage !
\nLiens utiles de documentation :
\nNous sommes heureux d'annoncer Docusaurus 2.4.
\nLa mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-3239a62bb56c9529ff255bc2c72e94f6.png\")
Dans #8236, nous avons ajouté la possibilité de fournir un nouvel attribut description pour les éléments de type link et category de la barre latérale de la documentation.
[
{
type: 'link',
label: 'Lien avec description',
href: 'https://docusaurus.io',
description: 'Une descriptions pour le lien',
},
{
type: 'category',
label: 'Catégorie avec description',
description: 'Une description de la catégorie',
objets : [],
},
];
Ces descriptions seront utilisées dans les pages d'index générées pour les catégories.
\n![\"Montre](\"https://docusaurus.io/fr/assets/images/sidebar-item-description-f38981b17f486bc09fb811c6992ef668.jpg\")
Dans #8708, nous avons ajouté la possibilité de forcer Docusaurus à s'initialiser en mode light (clair) ou dark (sombre) grâce à un nouveau paramètre docusaurus-theme de la chaîne de requête.
Ceci est utile pour assurer un thème cohérent lors de l'intégration d'une page Docusaurus existante dans une iframe ou WebView.
\nDans #8690, nous avons mis à jour notre plugin Remark @docusaurus/remark-plugin-npm2yarn avec de nombreuses corrections de bugs de conversion, un support de première classe pour pnpm, et la possibilité d'enregistrer des convertisseurs personnalisés produisant de nouveaux onglets.
\nRun these commands!
```bash npm2yarn
npm install
npm run build
npm run myCustomScript -- --some-arg
```
npm install
npm run build
npm run myCustomScript -- --some-arg
yarn install
yarn build
yarn myCustomScript --some-arg
pnpm install
pnpm run build
pnpm run myCustomScript --some-arg
Dans #8620 nous avons ajouté le support du plugin @docusaurus/plugin-google-gtag pour déclarer plusieurs ID de suivi.
\nmodule.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
gtag: {
trackingID: [
'G-<YOUR-NEW-GA4-ID>',
'UA-<YOUR-OLD-UA-ID>',
],
},
},
],
],
};
Google mettra fin à Universal Analytics le 1ᵉʳ juillet 2023.
Les utilisateurs de Docusaurus devraient par conséquent migrer vers Google Analytics 4. Google ne permet pas de migrer vos données Universal Analytics existantes vers votre nouveau domaine Google Analytics 4.
Pour préserver la continuité de vos statistiques, nous vous recommandons temporairement de rapporter les événements à deux identifiants de suivi simultanément : l'ancien (UA-*) et le nouveau (G-*). Reportez-vous au problème dédié pour plus de détails.
Dans #8736, nous avons amélioré la façon dont les messages d'erreur sont rendus et ajouté le support initial pour le rendu de la chaîne causale complète d'une erreur (voir ES2022 Error Cause).
\nPour le voir en action, cliquez ici :
Dans #8735, nous avons également clarifié les messages d'erreur liés à la barre de navigation pour aider les utilisateurs à comprendre ce qu'ils ont fait de mal.
\n![\"Capture](\"https://docusaurus.io/fr/assets/images/navbar-error-15eefab8e8d77aa4d605939956987164.jpg\")
Nous avons rendu possible la traduction de quelques nouveaux éléments :
\nprocess.env.DOCUSAURUS_CURRENT_LOCALE (expérimental) vous permettant de localiser votre fichier de configuration, y compris le titre du site, le slogan, la barre d'annonce, baseUrl...Nous avons ajouté la prise en charge de la traduction du thème par défaut pour plusieurs langues :
\n\nTerminer les traductions du thème est un effort en cours et un moyen facile de contribuer à Docusaurus. Nous ajoutons régulièrement de nouvelles fonctionnalités de thème, pour lesquelles nous avons souvent besoin de nouvelles traductions.
Voici les autres changements notables :
\nprefers-reduced-motion: reducedocSidebar dans le modèleConsultez l'entrée 2.4.0 du journal des modifications pour une liste exhaustive des changements.
", "url": "https://docusaurus.io/fr/blog/releases/2.4", "title": "Docusaurus 2.4", "summary": "Nous sommes heureux d'annoncer Docusaurus 2.4.", "date_modified": "2023-03-23T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/releases/2.3", "content_html": "Nous sommes heureux d'annoncer Docusaurus 2.3.
\nLa mise à jour devrait être facile : comme expliqué dans notre documentation sur le processus de version, les versions mineures respectent le versionnement sémantique.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-7e038d19ea67c686e90e1f599f7256d0.png\")
Google Tag Manager est un système de gestion des balises qui offre une grande flexibilité. Il permet aux équipes d'analyse et de marketing de charger facilement d'autres traceurs tiers et des balises d'analyse des incendies.
\nNous avons maintenant un paquet @docusaurus/plugin-google-tag-manager que vous pouvez utiliser en parallèle ou comme alternative au plugin existant gtag.js (référez-vous à ce doc pour comprendre quand utiliser telle ou telle solution).
Google va mettre fin à son Universal Analytics le 1er juillet 2023, et demande aux utilisateurs de migrer vers Google Analytics 4.
Par conséquent, nous sommes aussi en train de déprécier notre paquet existant @docusaurus/plugin-google-analytics. Les utilisateurs de Docusaurus doivent créer une nouvelle propriété Google Analytics 4 et migrer vers le plugin gtag.js, ou le plugin Google Tag Manager. Reportez-vous à l'issue Docusaurus dédiée pour plus de détails et des questions.
Il est maintenant possible de lier un onglet sélectionné à un paramètre de chaîne de requête. Lorsqu'un onglet est sélectionné, il sera stocké dans l'URL de votre navigateur en tant que paramètre de recherche ?qs-param=tab-value.
Cette fonction permet de créer des liens profonds vers un onglet de documentation spécifique qui sera présélectionné au chargement de la page.
\nLorsqu'elle est utilisée avec la prop groupId, la tab-value de la chaîne de requête a la priorité sur la valeur localStorage.
N'oubliez pas de consulter la documentation et la démo ci-dessous pour comprendre comment cela fonctionne :
\n\n<Tabs groupId=\"current-os\" queryString>
<TabItem value=\"android\" label=\"Android\">
Android
</TabItem>
<TabItem value=\"ios\" label=\"iOS\">
iOS
</TabItem>
</Tabs>
Android
iOS
Il est désormais possible d'imbriquer une admonition dans une autre en ajoutant des deux-points supplémentaires pour l'admonition extérieure/enveloppante :
\n::::tip[des admonitions imbriquées]
Vous pouvez désormais imbriquer une admonition dans une autre !
:::danger
Utilisez ceci avec parcimonie quand cela a du sens.
:::
:
:::
Vous pouvez désormais imbriquer une admonition dans une autre !
Utilisez ceci avec parcimonie quand cela a du sens.
:\n:::
createFeedItemsUne nouvelle option du plugin de blog feedOptions.createFeedItems vous donne plus de contrôle sur la génération de flux RSS/Atom. Il est maintenant possible de transformer/filtrer/limiter les éléments de flux grâce à un nouveau callback.
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
createFeedItems: async (params) => {
const {blogPosts, defaultCreateFeedItems, ...rest} = params;
return defaultCreateFeedItems({
// ne conserver que les 10 articles de blog les plus récents dans le flux
blogPosts: blogPosts.filter((item, index) => index < 10),
...rest,
});
},
},
},
},
];
Nous avons ajouté ou terminé la prise en charge par défaut de la traduction du thème pour plusieurs langues :
Traduire les thèmes représente un effort constant et un moyen facile de contribuer à Docusaurus. Nous ajoutons régulièrement de nouvelles fonctionnalités de thème, pour lesquelles nous avons souvent besoin de nouvelles traductions.
Voici les autres changements notables :
options.searchPagePath doit être correctement appliqué au pied de page de la modale de recherchedeploy du CLI comprend maintenant la config de l'url git insteadOfConsultez l'entrée 2.3.0 du changelog pour une liste exhaustive des changements.
Nous sommes heureux d'annoncer Docusaurus 2.2.
\nLa mise à jour devrait être facile : comme expliqué dans notre documentation sur le processus de version, les versions mineures respectent le versionnement sémantique.
\n![\"Carte](\"https://docusaurus.io/fr/assets/images/social-card-402517ac2205718a22585e627fe1351c.png\")
Dans le #7490, nous avons ajouté le support des diagrammes de Mermaid. Cela comble le vide entre GitHub Flavored Markdown qui a également ajouté la prise en charge récemment. Vous pouvez créer des diagrammes Mermaid en utilisant des blocs de code Markdown :
\n```mermaid
sequenceDiagram
participant Alice
participant Bob
Alice->>John: Hello John, how are you?
loop Health check
John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts <br/>prevail!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!
```
Veillez à consulter la documentation, et les exemples plus avancés
\nheadTagsDans le #8151, nous avons ajouté la possibilité d'appliquer des balises HTML arbitraire <head> à toutes les pages de votre site.
module.exports = {
headTags: [
{
tagName: 'link',
attributes: {
rel: 'icon',
href: '/img/docusaurus.png',
},
},
],
};
Nous avons fait plusieurs améliorations d'accessibilité :
\nNous avons rendu la validation plus stricte et amélioré les messages d'erreur :
\nsiteConfig.url plus strictement et avec un meilleur message d'erreururl et baseUrl plus sûrs et moins sensibles à la présence ou à l'absence d'un slash de début ou de finNous avons ajouté la prise en charge de la traduction du thème par défaut pour plusieurs langues :
\nTraduire les thèmes représente un effort constant et un moyen facile de contribuer à Docusaurus. Nous ajoutons régulièrement de nouvelles fonctionnalités de thème, pour lesquelles nous avons souvent besoin de nouvelles traductions.
Voici les autres changements notables :
\ndocusaurus swizzle a une nouvelle option --configConsultez l'entrée 2.2.0 du changelog pour une liste exhaustive des changements.
", "url": "https://docusaurus.io/fr/blog/releases/2.2", "title": "Docusaurus 2.2", "summary": "Nous sommes heureux d'annoncer Docusaurus 2.2.", "date_modified": "2022-10-29T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/2022/09/01/docusaurus-2.1", "content_html": "We are happy to announce Docusaurus 2.1, our very first minor version release.
\nLa mise à jour devrait être facile : comme expliqué dans notre documentation du processus de publication, les versions mineures respectent le versionnage sémantique.
\n![\"Docusaurus](\"https://docusaurus.io/fr/assets/images/social-card-8dc2413b4f9e86328bf77575e91171d7.png\")
In #8008, we simplified the usage of the<DocCardList> component, that is notably used on sidebar category generated index pages.
The items prop is now optional, and will be automatically inferred from the content of the parent sidebar category:
import DocCardList from '@theme/DocCardList';
- import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
- <DocCardList items={useCurrentSidebarCategory().items}/>
+ <DocCardList/>
De plus, nous avons fait en sorte qu'il soit possible de l'utiliser sur n'importe quel document, y compris les documents ordinaires non liés à une catégorie de la barre latérale.
\n![\"simplified](\"https://docusaurus.io/fr/assets/images/doc-card-list-e52d727eadceb3d21cfc0f851f09aa93.png\")
noindex improvementsWe improved the support of the noindex meta robots directive, a way to signal search engines you don't want a specific page to be indexed.
In #7963, we allow noindex to be configured on a per-docs-version basis.
Use the following plugin options to tell crawlers you don't want the 1.0.0 version to be indexed:
const options = {
versions: {
'1.0.0': {
noIndex: true,
},
},
};
En pratique, Docusaurus ajoutera la méta suivante à chaque page de cette version :
\n<meta name=\"robots\" content=\"noindex, nofollow\" />
In #7964, we also fixed a bug where the sitemap plugin would still contain pages that have a noindex directive. Now the sitemap plugin will reliably filter out all the pages containing noindex directives.
In #7952, it becomes possible to override default html meta tags you couldn't before:
\n<>
{siteConfig.noIndex && <meta name=\"robots\" content=\"nofollow, noindex\" />}
<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />
</>
It is now possible to use <Head> or themeConfig.metadata:
viewport metarobots meta: you could mark your site as noIndex, but except for specific pages that should be indexedIn #7953, we added default classic theme translations for the Ukrainian language.
\nCheck the 2.1.0 changelog entry for an exhaustive list of changes.
", "url": "https://docusaurus.io/fr/blog/2022/09/01/docusaurus-2.1", "title": "Docusaurus 2.1", "summary": "We are happy to announce Docusaurus 2.1, our very first minor version release.", "date_modified": "2022-09-01T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version" ] }, { "id": "https://docusaurus.io/fr/blog/2022/08/01/announcing-docusaurus-2.0", "content_html": "Today we are extremely happy to finally announce Docusaurus 2.0! 🥳️
\nChez 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.
\nAfter 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.
\n![\"social-card](\"https://docusaurus.io/fr/assets/images/social-card-736cfe55fc7bba07204176852d67c0d5.png\")
Pas beaucoup de temps ? Check what's new in Docusaurus 2.0!
Docusaurus is a static site generator that helps you ship beautiful documentation websites in no time.
\nFocus on your content: just write Markdown files. Docusaurus will generate an optimized website for you that's easy to host anywhere.
\nDocusaurus 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.
\n![\"Introducing](\"https://docusaurus.io/fr/assets/images/slash-introducing-411a16dd05086935b8e9ddae38ae9b45.svg\")
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.
\nUnless you're spinning up a documentation team with engineering resources, you\nprobably want Docusaurus!
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!
\nUsing Docusaurus for my tech blog has been a fantastic choice. It looks\ntremendous out-of-the-box and the awesome DX means I write way more
Try Docusaurus now with our online playgrounds and 5 minutes tutorial ⏱️
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.
\nAt 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.
\n\nIt 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.
\n\nRemarquez que les différents sites ci-dessus utilisent des couleurs différentes, mais ils se ressemblent beaucoup.
Docusaurus v1 has been very successful, but we started to question some architectural choices:
\nDocusaurus v2 was rebuilt from the ground up with a new modular architecture:
\nMore details in the Docusaurus 2 project announcement and v1 to v2 migration guide
\nDespite being in pre-release, it didn't take long for Docusaurus v2 to outgrow Docusaurus v1 in terms of NPM downloads:
\n![\"NPM](\"https://docusaurus.io/fr/assets/images/npm-downloads-f9d754a81ff372a5bae83c8751195e2b.png\")
La tendance de nos étoiles GitHub est très positive, en concurrence avec les principaux frameworks :
\n![\"GitHub](\"https://docusaurus.io/fr/assets/images/star-history-72ae014f60d05445753e9f690e41d347.png\")
Actuellement, Docusaurus v2 est déjà un grand succès avant même son lancement :
\nPlease add your site to our site showcase! It only takes a few seconds: just post a comment here.
We use Docusaurus everywhere now and love it
We've been using V2 since January and it has been great
Docusaurus is next level easy for literally everything you would need for\ndocumentation in your project.
Docusaurus is awesome. We use it
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.
\nMDX allows you to interleave React components in Markdown. This enables you to build top-notch interactive documentation experiences very easily.
\nUne démo vaut mieux qu'un long discours :
\n![\"Docusaurus](\"https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=353916&theme=light\")
### Give it a try: press that button!
import ColorModeToggle from '@theme/ColorModeToggle';
<ColorModeToggle/>
MDX has its own plugin system. Vous pouvez personnaliser votre expérience de création de Markdown et même créer votre propre syntaxe Markdown.
Docusaurus + MDX is great: we were able to implement a beautiful two-pane\nlayout and give the author fine-grained control on the placement of code and\ncorresponding prose.
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.
\n\nUsing the auto-generated sidebars makes it so simple to just create a page and\nnot worry about any other configuration.
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.
\nMore importantly, it enables our community to enhance Docusaurus with additional features.
\nSoulignons quelques exemples :
\n![\"redocusaurus](\"https://docusaurus.io/fr/assets/images/redocusaurus-5cf08a76be6f85090544417b82986cfb.png\")
![\"shiki-twoslash](\"https://docusaurus.io/fr/assets/images/shiki-twoslash-b74271684fa819a0175595409b2f323b.png\")
The plugin API was a breeze to use, and powerful enough that I could port the\ncode sample renderer from the TypeScript website site in a couple of hours.
![\"local](\"https://docusaurus.io/fr/assets/images/search-848f1f1b9eb0d1b710e1d1dec50fb84a.png\")
We have a curated list of outstanding plugins in our community resources page.
The plugin system in Docusaurus v2 has made expanding 1Password's developer\nportal so easy and fun. Nous sommes très heureux de vous montrer ce que nous avons conçu.
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.
\nDocusaurus theming gives a lot of flexibility on multiple levels:
\nI love Docusaurus Swizzling feature. Elle est à la fois opiniâtre et flexible. C'est super cool car un framework doit généralement sacrifier l'un au profit de l'autre.
This enables users willing to invest a bit more time on customizations to build sites that look different from others.
\n\nSo far it’s working out really nicely. Il a été très facile de le styliser comme nous le voulions. Aucun blocage.
Docusaurus 2 est doté d'une très longue liste de fonctions utiles :
\n
themeConfig options...Recently, I was shocked at how good Docusaurus is out of the box. Super solide, une bonne dose de configuration sans être excessive, et la possibilité de vraiment personnaliser le style si vous êtes plus courageux que moi.
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.
\nThe 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.
\nC'est important pour plusieurs raisons :
\nThe 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.
\nFrom now on, Docusaurus will release new major versions more frequently. In practice, you can expect a new major version every 2 to 4 months.
Major version numbers are not sacred, but we still group breaking changes together and avoid releasing major versions too often.
Check our release process documentation for details.
![\"Slash](\"https://docusaurus.io/fr/assets/images/slash-up-and-running-1c1f83f3064dcd56be41632c51be62ac.png\")
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.
\nUn échantillon des fonctionnalités figurant sur notre feuille de route pour les prochaines versions majeures de Docusaurus :
\nWe'd like to express our gratitude to all our contributors, including:
\nWe'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.
\nAt 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!
\nNow, let your imagination run wild 🤪!
\n— Slash
\n![\"Slash](\"https://docusaurus.io/fr/assets/images/slash-plushies-71b7a47477442dfcf890627669aba97d.jpg\")
Docusaurus a fait de grands progrès en 2021 ! We've seen a lot of traction and just crossed 30k stars on GitHub!
\nWe've reached full feature parity with v1 after the release of internationalization, announced our first beta, and welcomed significantly more users this year.
\nThe official v2 release is just around the corner! Follow the roadmap issue for any latest news.
\n![](\"https://docusaurus.io/fr/assets/images/thumbnail-dbb46fec970f4431a6846603224dd2fe.png\")
Commençons par passer en revue quelques faits marquants de cette année. Remember the todo-list from half a year ago? Il est temps de la sortir à nouveau et de voir jusqu'où nous sommes arrivés !
\nsidebars.js anymoreNotre base de code a également été perfectionnée au fil du temps. Nous avons amélioré la couverture des tests, migré tous les paquets vers TypeScript et réduit la taille de nos paquets publiés d'un maximum de 60 % !
\nDocusaurus v2 continue de croître régulièrement. L'installation de la v2 est maintenant 8 fois plus importante que la v1. En ce qui concerne les téléchargements hebdomadaires, nous avons assisté à une triple augmentation (+209,4 %), passant de 28 066 début janvier à un sommet de 86 846 à la mi-décembre.
\n![\"Docusaurus](\"https://docusaurus.io/fr/assets/images/npm-trend-1e69b5c9e35be8bd6d9ac6fbaaf313d7.png\")
(Ah, le classique repas de Noël...)
\nWe released 18 versions, going from 2.0.0-alpha.71 to 2.0.0-beta.14. C'est une version tous les 20 jours !
Notre tendance de star est également très positive. Compared to similar projects, we are growing at a faster rate:
\n![\"Stars](\"https://docusaurus.io/fr/assets/images/star-history-c7ba492b822fed1336d08fe449f87840.png\")
With an 8.4k increase in stars, we are ranked number 3 in this year's JavaScript rising stars of static site generators, preceded only by Next.js and Astro.
\n![\"Docusaurus](\"https://docusaurus.io/fr/assets/images/rising-stars-56326450d25b95f221f56db3b352c724.png\")
Our showcase has welcomed a few new \"favorite\" sites that showcase the true potential of Docusaurus 2's pluggable architecture.
\n![\"Iota](\"https://docusaurus.io/fr/assets/images/iota-light-d899be0c1eb939a5ad13e2ecca4eb951.png#gh-light-mode-only\")
![\"Iota](\"https://docusaurus.io/fr/assets/images/iota-dark-986d9518ba0e03583d734212ba93539d.png#gh-dark-mode-only\")
![\"Dyte](\"https://docusaurus.io/fr/assets/images/dyte-light-24caa76f96400453386185ae6bc06b8a.png#gh-light-mode-only\")
![\"Dyte](\"https://docusaurus.io/fr/assets/images/dyte-dark-b9748e4bcb4281880ff1856519d58b38.png#gh-dark-mode-only\")
![\"Ionic](\"https://docusaurus.io/fr/assets/images/ionic-light-b8a9c77c71a99f4c71a16584dac8ccf3.png#gh-light-mode-only\")
![\"Ionic](\"https://docusaurus.io/fr/assets/images/ionic-dark-17086f816052f02e84054fe002256ed9.png#gh-dark-mode-only\")
![\"Courier\"](\"https://docusaurus.io/fr/assets/images/courier-624bbae7cbef3b4e7533d1976e35f842.png\")
La créativité des utilisateurs de Docusaurus dépasse notre imagination 🤩 Nous sommes impatients de voir de plus en plus d'adoptants tirer parti des fonctionnalités de contenu de Docusaurus tout en explorant des designs de thèmes originaux ! If your site uses Docusaurus, we would love to have it in our showcase.
\nAs an active moderator on Discord, I can clearly see the community thriving. De nombreuses questions fréquemment posées sont désormais intégrées dans notre documentation, et certaines demandes de fonctionnalités ont également été mises en œuvre. Le projet et la communauté s'enrichissent mutuellement - à titre d'exemple, j'étais auparavant un contributeur de la communauté avant de devenir un mainteneur.
\nWe are constantly mentioned on X with inspirational feedback:
\n\n\n@docusaurus is amazing! je n'arrive pas à croire que c'est si simple à utiliser.
\nAucun plugin, outil ou étape de compilation supplémentaire. Cela fonctionne dès le départ.
\nI love @docusaurus. Sans Docusaurus, je n'aurais pas pu construire les API, les didacticiels et les blogs contenus dans mon site de manière efficace et belle dans le cadre de mon flux de travail.
\n
And we keep every one of them in our little box 😄 If you enjoy Docusaurus yourself, keep tagging us with your comments!
\nAs we approach the official release, we are interested in knowing more about what people are doing out there: plugin authors, creators of customized sites, and all new users – please keep us posted about your achievements so we can steer our development to better serve your needs.
\nAu cours des derniers mois, nous n'avons cessé de parler de la phase release-candidate de Docusaurus, et oui, elle est presque arrivée. We have created a dedicated milestone to keep track of all issues to solve before we can confidently progress to the next stage. In short, we want to build a more robust theming workflow, empowering creative site creators to customize our default theme without fearing breaking changes as they upgrade. Cela comprendra :
\nRead more about plans for Docusaurus 2.0 in this roadmap issue. La version 2.0 sera une plus meilleure version avec l'aide de la communauté, alors n'hésitez pas à partager vos opinions et vos suggestions sous l'une des rubriques des jalons !
\nComme l'équipe centrale travaille d'arrache-pied pour livrer la version de distribution générale, nous prévoyons de publier d'autres fonctionnalités utiles sous forme de versions mineures après la 2.0. We have even made further plans for architectural changes in 3.0!
\nAvec la sortie officielle de Docusaurus 2.0, nous sommes certains de voir beaucoup plus de nouvelles adoptions et de migrations depuis la v1.
\nWe'd like to express our gratitude to all the contributors in 2021, including:
\nÀ bientôt, 2021, et faisons un beau 2022 !
", "url": "https://docusaurus.io/fr/blog/2022/01/24/docusaurus-2021-recap", "title": "Récapitulatif de Docusaurus 2021", "summary": "Docusaurus a fait de grands progrès en 2021 ! We've seen a lot of traction and just crossed 30k stars on GitHub!", "date_modified": "2022-01-24T00:00:00.000Z", "author": { "name": "Joshua Chen", "url": "https://joshcena.com/" }, "tags": [ "récapitulatif" ] }, { "id": "https://docusaurus.io/fr/blog/2021/11/21/algolia-docsearch-migration", "content_html": "DocSearch is migrating to a new, more powerful system, which gives users their own Algolia application and new credentials.
\nDocusaurus site owners should upgrade their configuration with their new credentials by February 1, 2022, existing search indexes will be frozen and become read-only after this date.
\nDans les prochaines semaines, les propriétaires de sites Docusaurus recevront un courriel les invitant à rejoindre leur application personnelle Algolia.
\nThis email will include a new appId and apiKey to use in your Docusaurus configuration.
Les seules choses que vous avez à faire :
\nconst config = {
themeConfig: {
algolia: {
appId: '<NEW_APP_ID>',
apiKey: '<NEW_SEARCH_API_KEY>',
},
},
};
module.exports = config;
appId is now required.
Ces clés ne sont pas des secrets et peuvent être ajoutées à votre dépôt Git.
DocSearch is a program created by Algolia, which offers search to technical documentation of Open Source projects and technical blogs for free.
\nYou can read more here, and apply if you'd like to give it a try!
\nWith the upcoming stable release of DocSearch UI, we wanted to go further and provide better tooling for our users to improve their search, but also leverage the full potential of Algolia.
\nDocSearch now leverages the Algolia Crawler, which includes a web interface that will allow you to:
\n![\"The](\"https://docusaurus.io/fr/assets/images/crawler-overview-6224cc4c7b20511010652f3f4ed5904e.png\")
![\"The](\"https://docusaurus.io/fr/assets/images/editor-823e50dbed8e508bd5a69c708bab8928.png\")
But also, more Algolia features in your own Algolia app:
\n![\"The](\"https://docusaurus.io/fr/assets/images/index-overview-ca216346e6eee6881443644b6d7d8fe8.png\")
![\"The](\"https://docusaurus.io/fr/assets/images/index-analytics-f9c27da3900de6206e949736b1cd8101.png\")
And of course, a lot more, for free.
\nAu moment où nous écrivons ceci, nous sommes encore à un stade précoce de la migration. Nous faisons de petits lots chaque semaine mais nous allons augmenter la charge sous peu, alors soyez patient et gardez un œil sur votre boîte aux lettres, vous serez contacté dès que votre application Algolia sera prête !
\nWe wrote a small migration guide but you'll have more detailed information in the migration email.
\nPlease contact us via either email or DocSearch's Discord or on Docusaurus's Discord #algolia channel
\nFor any feedback regarding our documentation or the DocSearch UI component, you can open an issue on our GitHub repository, but also contact us via the methods above.
\nIn favor of the new infrastructure and DocSearch v3, we will no longer maintain our beloved DocSearch scraper and DocSearch v2, but the repositories will still be available and open to pull requests.
\nThe previous documentation (now called legacy) remains available as well as our run your own guide.
After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.
\nWith the announcement of this beta, the team is even more confident that Docusaurus 2 is ready for mainstream adoption!
\n![](\"https://docusaurus.io/fr/assets/images/image_cropped-2744c01b1fc0b451dbdb65a1d568fbff.png\")
Don't fear the beta tag!
\nDocusaurus 2 est largement adopté et se développe rapidement :
\n![\"Docusaurus](\"https://docusaurus.io/fr/assets/images/trend-2735e446f67fbcaa0811d103588e9b82.png\")
To get a fuller understanding of the quality of current Docusaurus 2 sites, our new 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!
\nDon't miss our favorite sites; they all stand out with something unique:
\n![\"A](\"https://docusaurus.io/fr/assets/images/favorites-7220082695a33eba77188ba7223c165c.png\")
It's hard to believe that the first alpha release v2.0.0-alpha.0 was 2 years ago 😳 , unusually long for a software alpha.
\nComme il s'agissait d'une ré-architecture importante de la base de code, nous voulions nous assurer que nous avions confiance dans la stabilité et les fonctionnalités de Docusaurus 2 avant de passer à la phase bêta, puisque la phase bêta suggère un haut niveau de qualité. We are happy to say that Docusaurus 2 has reached feature parity with Docusaurus 1 with i18n, and it has been successfully adopted by many Docusaurus sites (see i18n showcase).
\nNous sommes désormais convaincus que les fonctions principales de Docusaurus 2 sont suffisamment stables pour être en version bêta.
\nMaintenant que Docusaurus 2 est stable et que ses principales fonctionnalités sont terminées, l'objectif de la version bêta est d'inspirer la confiance aux nouveaux utilisateurs quant à la capacité de production de Docusaurus 2, de faire migrer un plus grand nombre d'utilisateurs de Docusaurus 1 vers la version 2, et de déprécier officiellement Docusaurus 1. Nous continuerons bien sûr à résoudre les problèmes et les bogues qui pourraient être découverts.
\nIn addition, we will use the beta phase to improve our theming system.
\nNous voulons réussir :
\neasier to implement a custom theme, including for ourselves. We want to provide multiple official themes (including Tailwind CSS) for a long time.
\nsafer to extend an existing theme: it can be painful to upgrade a highly customized Docusaurus site, as customizations can conflict with internal changes. Nous devons faire en sorte que la surface de l'API publique du thème soit plus explicite, et préciser ce qu'il est possible de personnaliser en toute sécurité.
\nWe will build a better theming infrastructure and refactor the classic theme to use it.
\nSi vous personnalisez votre site, vous pourriez trouver ces améliorations prévues très utiles.
\nAu cas où vous l'auriez manqué, nous avons récemment apporté deux améliorations majeures :
\nsidebars.js file anymore!Livraison de la version officielle 2.0 !
\nTo get there, we will continue to fix bugs and implement the most wanted features, including:
\nC'est un moment passionnant pour Docusaurus.
\nWe are inspired by the positive feedback about Docusaurus, and discover new sites online every single day.
\nNous sommes très heureux de cette version bêta. Nous avons recherché la qualité et la stabilité tout en continuant à essayer d'accroître l'adoption de Docusaurus. Pour ceux qui ont hésité à migrer un site Docusaurus existant vers Docusaurus 2, c'est le moment idéal pour le faire. Nous voulons que vous utilisiez l'infrastructure la plus récente lorsque nous abandonnerons Docusaurus 1 à la fin de cette période bêta. Faites-nous savoir comment nous pouvons aider.
\nMerci à tous ceux qui nous lisent et à toute la communauté qui soutient Docusaurus. 🤗
", "url": "https://docusaurus.io/fr/blog/2021/05/12/announcing-docusaurus-two-beta", "title": "Annonce de Docusaurus 2 Bêta", "summary": "After a lengthy alpha stage in order to ensure feature parity and quality, we are excited to officially release the first Docusaurus 2 beta.", "date_modified": "2021-05-12T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version", "bêta" ] }, { "id": "https://docusaurus.io/fr/blog/2021/03/09/releasing-docusaurus-i18n", "content_html": "Today, we officially release Docusaurus 2 i18n (internationalization), as part of 2.0.0-alpha.71.
\nDocusaurus 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.
\nWe went the extra mile, and the new i18n support is even better than in Docusaurus 1.
\nIn this post, we will present you the translation workflow, explain some design decisions and showcase early adopter sites that just went live: Jest, Redwood, and Datagit.
\nWe also dogfood the i18n support on the Docusaurus 2 site itself, and this post is already available in English and French!
\nYou can translate a Docusaurus site in 3 simple steps:
\ndocusaurus.config.jsThe i18n support is very flexible and based on the filesystem.
\nThe i18n tutorial is the best way to get started, and we provide help to use Git or Crowdin.
\nLes objectifs du système Docusaurus i18n sont :
\nhreflangWe worked with a few volunteers to dogfood the i18n support before releasing it.
\nWe have made it possible to upgrade a translated Docusaurus 1 site to Docusaurus 2.
\nJest, using Docusaurus 1 and Crowdin was one of those sites.
\nThe Docusaurus 2 migration was successful and the new site is now deployed in production (announcement post).
\n![\"Jest's](\"https://docusaurus.io/fr/assets/images/jest-59f159eb97ecd87655cf47ec5cc00d47.png\")
Redwood is a React full-stack Jamstack framework.
\nThey were looking for a solution to create an internationalized learning platform, and became early adopters of Docusaurus 2 i18n for learn.redwoodjs.com, using Crowdin to get it translated to French.
\n![\"Redwood's](\"https://docusaurus.io/fr/assets/images/redwood-c3155187911b62428e0cc1e8b662de76.png\")
The i18n system should work with any language, including Right-to-Left languages.
\nDatagit.ir is using Farsi, and a simple configuration option is able to flip the Docusaurus theme to add the required Right-to-Left support.
\n![\"Datagit's](\"https://docusaurus.io/fr/assets/images/datagit-9cff7b631eaa43b00d9e1373359abfb1.png\")
Nous espérons sincèrement que vous adopterez et apprécierez le nouveau soutien de l’i18n.
\nCette fonctionnalité n'a pas été facile, et nous voudrions remercier tous ceux qui ont été impliqués dans ce voyage :
\nMerci d'avoir pris le temps de lire !
\n🙏 And please, add your brand new i18n sites to our showcase page. We accept any all polished Docusaurus site here, and we are working on a redesign allowing you to filter sites by features.
", "url": "https://docusaurus.io/fr/blog/2021/03/09/releasing-docusaurus-i18n", "title": "Publication de Docusaurus i18n", "summary": "Today, we officially release Docusaurus 2 i18n (internationalization), as part of 2.0.0-alpha.71.", "date_modified": "2021-03-09T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "version", "I18n" ] }, { "id": "https://docusaurus.io/fr/blog/2021/01/19/docusaurus-2020-recap", "content_html": "2020 was great for Docusaurus, despite a regrettable start and a tumultuous year for everyone.
\nWe continued to invest in Docusaurus 2, and made it reach full feature parity with Docusaurus 1.
\nWe now recommend Docusaurus 2 as the default choice to start a new Docusaurus project and encourage v1 users to migrate to Docusaurus 2.
\nWe are still in alpha, but expect some good news very soon!
\n![\"Three](\"https://docusaurus.io/fr/assets/images/docusaurus-plushie-banner-a60f7593abca1e3eef26a9afa244e4fb.jpeg\")
Nous avons travaillé sur de nombreuses fonctionnalités cette année et nous voudrions en souligner les plus importantes :
\n@canary npm tag to use the upcoming release before anyone elseThe plan to rebuild Docusaurus from scratch in 2019 paid off: after a slow start, Docusaurus 2 has been widely adopted and has already outgrown Docusaurus 1 usage.
\n![\"Docusaurus](\"https://docusaurus.io/fr/assets/images/docusaurus-npm-trends-3c618d573fc9ca319e54667383ea1e01.png\")
Notable projects, startups, large companies, and individuals adopted Docusaurus 2 (showcase):
\nWe helped large scale Docusaurus 1 sites to upgrade, ensuring a proper migration path and feature parity.
\nReact Native was successfully upgraded to Docusaurus 2 (archived v1 site):
\n![\"React](\"https://docusaurus.io/fr/assets/images/react-native-screenshot-d5ace12ce89fe59dc14ac25859685b01.png\")
Localized Docusaurus 1 sites (like Jest) will be able to upgrade too:
\n![\"Jest's](\"https://docusaurus.io/fr/assets/images/jest-screenshot-fa8ba3dd1b0ebbf923ed56274f0e4f5e.png\")
We also saw the first right-to-left Docusaurus 2 site published:
\n![\"Datagit's](\"https://docusaurus.io/fr/assets/images/datagit-rtl-screenshot-0def4b4e4d5f458ea864774e78b0bf8f.png\")
We have welcomed Major League Hacking (MLH) fellows for 2 seasons already.
\nWe are very thankful for the various contributions they made, such as:
\nNous sommes impatients de poursuivre cette collaboration en 2021.
\nDmitry Vinnik (Developer Advocate @ Facebook) explains Docusaurus in 60 seconds or 15min videos.
\nRachel Nabors (Documentation Engineer @ Facebook) talked a bit about Docusaurus in React Native Radio 178 (podcast), and William Candillon the React Native website migration (video).
\nDe nombreux articles de blog ont été publiés :
\nThe Docusaurus community continues to grow, the Discord server is quite active, and Stack Overflow questions keep being posted.
\nThe modular architecture of Docusaurus 2 allowed the community to build and publish third-party plugins. As we would like to federate better our community, if you are building a plugin, please let us know.
\nAs 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.
\nWith 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.
\nWe still have a few major features that we would like to work on:
\nHuge thanks to the community for their contributions in 2020, especially:
\nÀ la santé d'une bonne année 2021 ! 🎉
", "url": "https://docusaurus.io/fr/blog/2021/01/19/docusaurus-2020-recap", "title": "Récapitulatif de Docusaurus 2020", "summary": "2020 was great for Docusaurus, despite a regrettable start and a tumultuous year for everyone.", "date_modified": "2021-01-19T00:00:00.000Z", "author": { "name": "Sébastien Lorber", "url": "https://thisweekinreact.com" }, "tags": [ "récapitulatif" ] }, { "id": "https://docusaurus.io/fr/blog/2020/01/07/tribute-to-endi", "content_html": "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.
\nIl est impossible de ne pas souligner l'impact d'Endi sur ce projet :
\nEn y repensant maintenant, il est absolument incroyable de voir tout ce qu'Endi a accompli sur Docusaurus, compte tenu des problèmes de santé qu'il a dû affronter.
\nNous travaillons sur les moyens de faire honneur aux contributions d'Endi - un autocollant commémoratif, peut-être - et nous sommes ouverts aux idées. Leave a comment here or tweet if you have a suggestion.
\nLe projet Docusaurus ne sera pas le même sans Endi, et il manquera beaucoup à ceux d'entre nous qui ont travaillé avec lui. 😔
\n![\"A](\"https://docusaurus.io/fr/assets/images/endi-f942c4eafb5f650832b4327bfbadae4f.jpg\")