mdBook : liens internes : Chemins relatifs

Nous devons utiliser des liens internes pour écrire des liens vers des ressources du projet mdBook en cours.

L’utilisation de liens internes facilite la portabilité du projet : changement de nom de domaine ou de l’emplacement du projet en ligne.

IMPORTANT : Comme je l’explique dans Bonne réponse, il convient de prendre la bonne habitude d’écrire tous nos liens avec des chemins relatifs depuis la racine du projet mdBook.

Nous pouvons écrire un lien interne vers :

• un fichier image ;
• un fichiers.md en tant que liens web ouvrant la page correspondante ;
• un chapitre de page mdBook en tant que lien Web ouvrant la page correspondante en affichant et surlignant le chapitre de page ;
• un fichier.md à insérer ;
• un fichier-de-code à insérer, qui peut être un fichiers.rs écrit en langage Rust.

Les liens des chapitres du sommaire mdBook utilisent les mêmes règles que les liens internes des pages mdBook.

Syntaxe des liens internes

Pour écrire un lien vers un contenu du même projet mdBook, nous utilisons un lien interne qui s’écrit comme suit.

Choix des liens web pour illustrer

Je prends ici l’exemple de l’écriture d’un lien Web ([texte](lien-interne)).

Les principes décrits ici pour l’écriture d’un lien interne pour un lien Web s’appliquent dans les autres cas d’écriture de liens.

Tous les liens web que nous voyons ci-après sous écrits sous la forme : [Texte](lien) qui s’affiche : Texte et qui crée un lien Web vers le contenu souhaité.

Lien Web vers une autre page mdBook dans le même dossier

Pour écrire un lien interne vers un fichier.md dans le même dossier, nous pouvons écrire [Texte](fichier.md), mais je recommande d’utiliser un lien complet depuis la racine du projet mdBook soit [Texte](/dossier/sous-dossier/fichier.md) (si dossier et sous-dossier il y a).

Lien Web vers un fichier.md dans un sous-dossier

Dans le cas où le fichier.md destination est dans un sous-dossier dossier, nous pouvons écrire [Texte](sous-dossier/fichier.md), mais je recommande d’utiliser un lien complet depuis la racine du projet mdBook soit [Texte](/dossier/sous-dossier/fichier.md) (le chemin est celui depuis nom-du-projet/src/).

Lien depuis un fichier dans un sous-dossier

Nous avons cette structure de dossiers et fichiers :

nom-du-projet/
├── src/
    ├── fichier.md
    ├── dossier-1/
    │   ├── fichier-du-dossier-1.md
    ├── dossier-2/
        ├── fichier-du-dossier-2.md

Nous pouvons écrire un lien interne vers fichier.md dans fichier-du-dossier-1.md sous cette forme : [Texte](../fichier.md), mais nous écrirons plutôt [Texte](/fichier.md)

Pour écrire un lien vers fichier-du-dossier-2.md dans fichier-du-dossier-1.md, nous pouvons écrire [Texte](../dossier-2/fichier-du-dossier-2.md), mais nous écrirons plutôt [Texte](/dossier-2/fichier-du-dossier-2.md).

Avec ou sans le ./

Lorsque nous écrivons un lien interne vers un fichier, nous pouvons utiliser le format avec un ./ du dossier en cours, sous la forme [Texte](./dossier/fichier.md) mais ce n’est pas la forme proposée par la documentation officielle mdBook, et ce n’est, donc, pas recommandé, comme le style répétitif que j’utilise ici devrait vous avoir aidé à le comprendre et, surtout, le retenir.

Lien vers le site Web mdBook en cours

Si nous éditons un fichier.md dans le dossier source, le lien interne vers le site Web mdBook en cours d’édition est [Texte](/) (et [Texte](./) aussi, mais ce n’est pas l’écriture recommandée).

Lien depuis un sous-dossier

Si nous avons cette structure de dossiers et de fichiers :

my-book/
├── src/
    ├── dossier/
        ├── fichier.md

Le lien vers le site Web mdBook depuis fichier.md est [Texte](/) (et [Texte](../), mais ce n’est pas l’écriture recommandée).

Lien Web vers un chapitre de page mdBook

Voir : mdBook : Liens internes : Chapitres de pages mdBook.

Les liens (/) et (./) ne fonctionnent pas en mode accès direct aux fichiers

En principe, nous n’accédons pas à notre site en cours de création par accès direct aux fichiers, nous utilisons mdbook serve dont je parle dans mdbook serve : Visualiser nos modifications en continu.

Si nous consultons le site Web mdBook que nous sommes en train d’éditer par accès direct aux fichiers sur notre machine, les liens internes de type (/) ou (./) nous renvoient vers l’affichage du dossier local nom-du-projet/book (par défaut), par exemple dans mon cas pour ce projet : ¹

1. Cette image est « collector », alors je la conserve. ↩