Introduction des docs

La fonction de documentation fournit aux utilisateurs un moyen d'organiser les fichiers Markdown dans un format hiérarchique.

info

Check the Docs Plugin API Reference documentation for an exhaustive list of options.

La documentation de votre site est organisée en quatre niveaux, du plus bas au plus haut :

1. Pages individuelles.
2. Barres latérales.
3. Versions.
4. Instances de plugin.

The guide will introduce them in that order: starting from how individual pages can be configured, to how to create a sidebar or multiple ones, to how to create and manage versions, to how to use multiple docs plugin instances.

Docs-only mode

Un site Docusaurus récemment initialisé a la structure suivante :

example.com/                                -> generated from `src/pages/index.js`

example.com/docs/intro                      -> generated from `docs/intro.md`
example.com/docs/tutorial-basics/...        -> generated from `docs/tutorial-basics/...`
...

example.com/blog/2021/08/26/welcome         -> generated from `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post   -> generated from `blog/2021-08-01-mdx-blog-post.mdx`
...

All docs will be served under the subroute docs/. But what if your site only has docs, or you want to prioritize your docs by putting them at the root?

Supposons que vous ayez les éléments suivants dans votre configuration :

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        /* docs plugin options */
      },
      blog: {
        /* blog plugin options */
      },
      // ...
    },
  ],
};

Pour entrer en mode docs-uniquement, changez le comme ceci :

docusaurus.config.js

module.exports = {
  // ...
  presets: [
    '@docusaurus/preset-classic',
    {
      docs: {
        routeBasePath: '/', // Serve the docs at the site's root
        /* other docs plugin options */
      },
      blog: false, // Optional: disable the blog plugin
      // ...
    },
  ],
};

Note that you don't necessarily have to give up on using the blog or other plugins; all that routeBasePath: '/' does is that instead of serving the docs through https://example.com/docs/some-doc, they are now at the site root: https://example.com/some-doc. The blog, if enabled, can still be accessed through the blog/ subroute.

Don't forget to put some page at the root (https://example.com/) through adding the front matter:

docs/intro.md

---
slug: /
---

Cette page sera la page d'accueil lorsque les utilisateurs visiteront https://example.com/.

attention

If you added slug: / to a doc to make it the homepage, you should delete the existing homepage at ./src/pages/index.js, or else there will be two files mapping to the same route!

Maintenant, la structure du site sera comme ceci :

example.com/                       -> generated from `docs/intro.md`
example.com/tutorial-basics/...    -> generated from `docs/tutorial-basics/...`
...

astuce

Il y a aussi un « mode blog-uniquement » pour ceux qui ne veulent utiliser que la fonction blog de Docusaurus 2. Vous pouvez utiliser la même méthode décrite ci-dessus. Follow the setup instructions on Blog-only mode.