Aller au contenu principal
Version : 3.10.0

Créer un doc

Créez un fichier Markdown greeting.md et placez-le dans le répertoire docs.

website # root directory of your site
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...
---
description: Create a doc page with rich content.
---

# Hello from Docusaurus

Are you ready to create the documentation site for your open source project?

## Headers

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

## Only h2 and h3 will be in the TOC by default.

You can configure the TOC heading levels either per-document or in the theme configuration.

The headers are well-spaced so that the hierarchy is clear.

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times
remarque

Tous les fichiers préfixés par un underscore (_) sous le répertoire docs sont traités comme des pages « partielles » et seront ignorés par défaut.

Pour en savoir plus sur l'importation de pages partielles.

Frontmatter du doc​

Le front matter est utilisé pour fournir des métadonnées supplémentaires pour votre page de doc. Le frontmatter est optionnel — Docusaurus pourra déduire toutes les métadonnées nécessaires sans le frontmatter. Par exemple, la fonctionnalité des tags de doc introduite ci-dessous nécessite l'utilisation du front matter. Pour connaître tous les champs possibles, consultez la documentation de l'API.

Tags de doc​

Tags are declared in the front matter and introduce another dimension of categorization in addition to the docs sidebar.

It is possible to define tags inline, or to reference predefined tags declared in a tags file (optional, usually docs/tags.yml).

In the following example:

  • docusaurus references a predefined tag key declared in docs/tags.yml
  • Releases is an inline tag, because it does not exist in docs/tags.yml
docs/my-doc.md
---
tags:
  - Releases
  - docusaurus
---

# Title

Content
docs/tags.yml
docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: 'Docs related to the Docusaurus framework'
astuce

Les tags peuvent également être déclarés avec tags: [Demo, Pour commencer].

Pour en savoir plus sur toutes les syntaxes de tableau Yaml.

Organisation de la structure du dossier​

La façon dont les fichiers Markdown sont organisés sous le dossier docs peut avoir plusieurs impacts sur la génération de contenu Docusaurus. Cependant, la plupart d'entre eux peuvent être découplés de la structure des fichiers.

ID du document​

Chaque document a un id unique. Par défaut, l'id d'un document est le nom du document (sans l'extension) relatif au répertoire racine de la documentation.

Par exemple, greeting.md a pour ID greeting et guide/hello.md a pour ID guide/hello.

website # Root directory of your site
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

Cependant, la dernière partie de l'id peut être définie par l'utilisateur dans le front matter. Par exemple, si le contenu de guide/hello.md est défini comme ci-dessous, son id final est guide/part1.

---
id: part1
---

Lorem ipsum

L'ID est utilisé pour faire référence à un document lors de l'écriture manuelle de barres latérales ou lors de l'utilisation de composants ou de hooks liés à la mise en page de la documentation.

URL du doc​

By default, the document's URL location is derived from the document id, which in turn is based on the document's file path.

If a file is named one of the following, the file name won't be included in the URL:

  • Nommé comme index (insensible à la casse) : docs/Guides/index.md
  • Nommé comme README (insensible à la casse) : docs/Guides/README.mdx
  • Même nom que le dossier parent : docs/Guides/Guides.md

In all cases, the default slug would only be /Guides, without the /index, /README, or duplicate /Guides segment.

remarque

This convention is exactly the same as the category index convention. However, the isCategoryIndex configuration does not affect the document URL.

Use the slug front matter to provide an explicit document URL and override the default one.

For example, suppose your site structure looks like this:

website # Root directory of your site
└── docs
    └── guide
        └── hello.md

By default, hello.md will be available at /docs/guide/hello. Vous pouvez changer l'emplacement de son URL en /docs/bonjour :

---
slug: /bonjour
---

Lorem ipsum

slug sera ajouté au routeBasePath du plugin doc, qui est /docs par défaut. Consultez le Mode Docs uniquement pour savoir comment supprimer la partie /docs de l'URL.

remarque

It is possible to use:

  • des slugs absolus : slug: /mySlug, slug: /...
  • des slugs relatifs : slug: mySlug, slug: ./../mySlug...
astuce

Changing a document's filename or id, will change its default URL. To prevent breaking permalinks when renaming files, we recommend setting an explicit slug to keep your URLs stable.

Making a document available at the root​

Si vous voulez qu'un document soit disponible à la racine, et que vous avez un chemin comme https://docusaurus.io/docs/, vous pouvez utiliser le slug du front matter :

---
id: my-home-doc
slug: /
---

Lorem ipsum

Lors de l'utilisation de barres latérales générées automatiquement, la structure du fichier déterminera la structure de la barre latérale.

Notre recommandation pour l'organisation du système de fichiers est la suivante : faites en sorte que votre système de fichiers reflète la structure de la barre latérale (afin de ne pas avoir à écrire à la main votre fichier sidebars.js), et utilisez slug du front matter pour personnaliser les URL de chaque document.