Navigation and Sidebars

Faire référence aux documents du site

If you want to reference another document in your docs directory (or the location you set via the optional customDocsPath path site configuration option), then you just use the name of the document you want to reference.

Par exemple, si vous êtes dans doc2.md et que vous voulez faire référence à doc1.md:

Je fais référence à un [document](doc1.md).

Comment les documents sont liés

Les nouveaux fichiers markdown dans docs apparaîtront sous forme de pages sur le site web. Les liens vers ces documents sont créés d'abord en utilisant l'id dans l'entête de chaque document. S'il n'y a pas de champ id, alors le nom du fichier servira de nom de lien.

Par exemple, la création d'un fichier vide tel que docs/getting-started.md activera l'URL de la nouvelle page avec /docs/getting-started.html.

Supposons que vous ajoutiez ceci à votre document :

id: intro
title: Pour commencer
---
Mon nouveau contenu ici..

Si vous définissez le champ id dans l'entête du fichier markdown, le doc sera alors accédé à partir d'une URL de la forme /docs/intro.html.

Vous avez besoin d'un champ id pour pouvoir ajouter le document à la barre latérale.

Ajouter des documents à une barre latérale

Souvent, vous voudrez ajouter un document à une barre latérale qui sera associée à l'un des entêtes dans la barre de navigation supérieure du site web. La barre latérale la plus courante, et celle qui est installée lorsque Docusaurus est initialisé, c'est la barre latérale docs.

« docs » est juste un nom. Il n'a pas de signification particulière. Vous pouvez le modifier comme vous le souhaitez.

Vous configurez le contenu de la barre latérale et l'ordre de ses documents, dans le fichier website/sidebars.json.

Jusqu'à ce que vous ajoutiez votre document à website/sidebars.json, il ne sera accessible que par une URL directe. Le doc n'apparaîtra dans aucune barre latérale.

Dans sidebars.json, ajoutez l'id que vous avez utilisé dans l'entête du document à la barre latérale/catégorie existante. Dans le cas ci-dessous, docs est le nom de la barre latérale et Getting Started est une catégorie dans la barre latérale.

{
  "docs": {
    "Getting Started": [
      "getting-started"
    ],
    ...
  },
  ...
}

Ou vous pouvez créer une nouvelle catégorie dans la barre latérale :

{
  "docs": {
    "Ma nouvelle catégorie de la barre latérale": [
      "getting-started"
    ],
...
  },
  ...
}

Cependant, pour un document situé dans un sous-répertoire de docs comme ci-dessous :

docs
└── dir1
    └── getting-started.md

Vous devez fournir le_répertoire/id au lieu d'id dans sidebars.json.

{
  "docs": {
    "Ma nouvelle catégorie de la barre latérale": [
      "dir1/getting-started"
    ],
...
  },
  ...
}

Ajouter des sous-catégories

Il est possible d'ajouter des sous-catégories à une barre latérale. Au lieu d'utiliser les ID comme contenu du tableau des catégories selon les exemples précédents, vous pouvez passer un objet où les clés seront le nom de la sous-catégorie et la valeur d'un tableau d'ID pour cette sous-catégorie.

{
  "docs": {
    "Mon exemple de catégorie": [
      "exemples",
      {
        "type": "subcategory",
        "label": "Mon exemple de sous-catégorie",
        "ids": [
          "mes-exemples",
          ...
        ]
      },
      {
        "type": "subcategory",
        "label": "Ma sous-catégorie suivante",
        "ids": [
          "quelques-autres-exemples"
        ]
      },
      "encore-plus-exemples",
      ...
    ],
    ...
  }
}

/*
Ce qui précède va générer :

- Mon exemple de catégorie
  - exemples
  - Mon exemple de sous-catégorie
    - mes-exemples
    ...
  - Ma sous-catégorie suivante
    - quelques-autres-exemples
  - encore-plus-exemples
  ...
*/

Ajouter de nouvelles barres latérales

You can also put a document in a new sidebar. In the following example, we are creating an examples-sidebar sidebar within sidebars.json that has a category called My Example Category containing a document with an id of my-examples.

{
  "exemples-barre-laterale": {
    "Mon exemple de catégorie": [
      "mes-exemples"
    ],
    ...
  },
  ...
}

It is important to note that until you add a document from the "examples-sidebar" sidebar to the nav bar, it will be hidden.

Additions to the Site Navigation Bar

To expose sidebars, you will add click-able labels to the site navigation bar at the top of the website. You can add documents, pages and external links.

Adding Documents

After creating a new sidebar for the site by adding it to sidebars.json, you can expose the new sidebar from the top navigation bar by editing the headerLinks field of siteConfig.js.

{
  headerLinks: [
    ...
    { doc: 'mes-exemples', label: 'Exemples' },
    ...
  ],
  ...
}

A label called Examples will be added to the site navigation bar and when you click on it at the top of your site, the examples-sidebar will be shown and the default document will be my-examples.

Adding Custom Pages

To add custom pages to the site navigation bar, entries can be added to the headerLinks of siteConfig.js. For example, if we have a page within website/pages/help.js, we can link to it by adding the following:

{
  headerLinks: [
    ...
    { page: 'help', label: 'Help' },
    ...
  ],
  ...
}

A label called Help will be added to the site navigation bar and when you click on it at the top of your site, the content from the help.js page will be shown.

Adding External Links

Custom links can be added to the site navigation bar with the following entry in siteConfig.js:

{
  headerLinks: [
    ...
    { href: 'https://github.com/facebook/docusaurus', label: 'GitHub' },
    ...
  ],
  ...
}

A label called GitHub will be added to the site navigation bar and when you click on it at the top of your site, the content of the external link will be shown.

To open external links in a new tab, provide an external: true flag within the header link config.

Site Navigation Bar Positioning

You have limited control where the search and languages dropdown elements are shown in the site navigation bar at the top of your website.

Search

If search is enabled on your site, your search bar will appear to the right of your links. If you want to put the search bar between links in the header, add a search entry in the headerLinks config array:

{
  headerLinks: [
    { doc: 'foo', label: 'Foo' },
    { search: true },
    { doc: 'bar', label: 'Bar' },
  ],
  ...
}

Languages Dropdown

If translations are enabled on your site, the language dropdown will appear to the right of your links (and to the left of the search bar, if search is enabled). If you want to put the language selection drop down between links in the header, add a languages entry in the headerLinks config array:

{
  headerLinks: [
    { doc: 'foo', label: 'Foo' },
    { languages: true },
    { doc: 'bar', label: 'Bar' },
  ],
  ...
}

Active Links In Site Navigation Bar

The links in the top navigation bar get siteNavItemActive and siteNavGroupActive class names to allow you to style the currently active link different from the others. siteNavItemActive is applied when there's an exact match between the navigation link and the currently displayed web page.

This does not include links of type href which are meant for external links only. If you manually set an href in your headerLinks to an internal page, document, or blog post, it will not get the siteNavItemActive class even if that page is being displayed.

The siteNavGroupActive class will be added to these links:

doc links that belong to the same sidebar as the currently displayed document
The blog link when a blog post or the blog listing page is being displayed

These are two separate class names so you can have the active styles applied to either exact matches only or a bit more broadly for docs that belong together. If you don't want to make this distinction you can add both classes to the same CSS rule.

Secondary On-Page Navigation

We support secondary on-page navigation so you can quickly see the topics associated with a given document. To enable this feature, you need to add the onPageNav site configuration option to your siteConfig.js.

{
  onPageNav: 'separate',
  ...
}

Currently, 'separate' is the only option available for this field. This provides a separate navigation on the right side of the page.

Catégories pliables

Pour les sites avec une quantité importante de contenu, nous prenons en charge l'option d'étendre / réduire les liens et les sous-catégories sous les catégories. Pour activer cette fonctionnalité, définissez l'option docsSideNavCollapsible configuration du site option dans siteConfig.js à true.

{
  docsSideNavCollapsible: true,
  ...
}