Liens Markdown
Il existe deux façons d'ajouter un lien vers une autre page : par un chemin d'accès à l'URL et par un chemin d'accès au fichier.
- [chemin d'accès par l'URL vers un autre document](./installation)
- [chemin d'accès par le fichier vers un autre document](./installation.mdx)
Les chemins aux URL ne sont pas traités par Docusaurus, et vous pouvez les considérer comme rendant directement <a href="./installation">
, c'est-à-dire qu'ils seront résolus en fonction de l'emplacement de l'URL de la page, plutôt que de son emplacement dans le système de fichiers.
Si vous voulez faire référence à un autre fichier Markdown inclus par le même plugin, vous pourriez utiliser le chemin relatif du document vers lequel vous voulez établir un lien. Le chargeur Markdown de Docusaurus convertira le chemin du fichier vers le chemin de l'URL du fichier cible (et supprimera donc l'extension .md
).
Par exemple, si vous êtes dans docs/dossier/doc1.md
et que vous voulez faire référence à docs/dossier/doc2.md
, docs/dossier/sous-dossier/doc3.md
et docs/autreDossier/doc4.md
:
Je fais référence à un [document](doc2.mdx).
Référence vers un autre [document dans un sous-dossier](sous-dossier/doc3.mdx).
Le référencement de [document relatif](../autreDossier/doc4.mdx) fonctionne également.
Les chemins de fichiers relatifs sont résolus dans le répertoire du fichier courant. Les chemins absolus de fichier, par contre, sont résolus par rapport à la racine de contenu, généralement docs/
, blog/
, ou des chemins localisés comme i18n/zh-Hans/plugin-content-docs/current
.
Here are some examples of file path links and how they get resolved, assuming the current file is website/docs/category/source.mdx
:
[link](./target.mdx)
is resolved from the current file's directorywebsite/docs/category
.[link](../target.mdx)
is resolved from the parent file's directorywebsite/docs
.[link](/target.mdx)
is resolved from the docs content rootwebsite/docs
, using in priority the localized docs.[link](target.mdx)
is resolved from the current directorywebsite/docs/category
, then from the docs content roots, then from the site root.
Les chemins absolus de fichiers peuvent également être relatifs au répertoire du site. However, beware that links that begin with /docs/
, /blog/
or @site/
are not portable as you would need to manually update them if you create new doc versions or localize them:
[link](/docs/target.mdx)
is resolved from the site rootwebsite
(⚠️ less portable).[link](@site/docs/target.mdx)
is relative to the site rootwebsite
(⚠️ less portable).
L'utilisation des chemins relatifs du fichier (avec des extensions .md
) au lieu des liens URL relatifs fournit les avantages suivants :
- Les liens continueront à fonctionner sur l'interface GitHub et de nombreux éditeurs Markdown
- Vous pouvez personnaliser les slugs des fichiers sans avoir à mettre à jour tous les liens
- Le déplacement des fichiers dans les dossiers peut être suivi par votre éditeur, et certains éditeurs peuvent mettre à jour automatiquement les liens du fichier
- Un doc versionné sera lié à un autre doc de la même version
- Les liens d'URL relatifs sont très susceptibLes de se rompre si vous mettez à jour la config
trailingSlash
Les références de fichier Markdown ne fonctionnent que lorsque les fichiers source et cible sont traités par la même instance de plugin. Ceci est une limitation technique de notre architecture du traitement Markdown et sera corrigé dans le futur. Si vous liez des fichiers entre des plugins (par exemple, un lien vers une page de doc à partir d'un article du blog), vous devez utiliser des liens URL.