Lien relatif GitHub dans le fichier Markdown


832

Existe-t-il un moyen de créer une ancre URL <a>, un lien depuis un fichier Markdown vers un autre fichier du même référentiel et de la même branche (c'est-à-dire un lien relatif à la branche actuelle)?

Par exemple, dans la branche principale, j'ai un fichier README.md, que j'aimerais faire quelque chose comme:

# My Project
is really really cool. My Project has a subdir named myLib, see below.

## myLib documentation
see documentation [here](myLib/README.md)

Cela me permettrait de créer un lien entre un .md et un autre au sein de la même branche et de ne pas avoir à me soucier de la branche dans laquelle je me trouve (éviter d'avoir à faire une URL absolue qui inclut le nom de la branche github.com).

Voici un exemple pratique de ce que je veux dire:

  1. GOTO http://github.com/rynop/testRel , le lien ne fonctionne pas.
  2. GOTO http://github.com/rynop/testRel/blob/master/README.md , lien fonctionne.

Cela est attendu car à ce stade, l'URL de départ se trouve dans la branche. Maintenant, comment puis-je l'obtenir pour récupérer la branche actuelle dans le fichier README.md à la racine du référentiel?

Mise à jour : j'ai ouvert un problème avec GitHub pour cette demande de fonctionnalité.


21
Enfin : les liens relatifs sont désormais pris en charge! J'ai mis à jour ma réponse :)
VonC

Ce sont toutes de bonnes informations si vous essayez d'ouvrir un autre .md ou d'aller sur une autre page Web http / s ou html ou même .jpg, .png ou jpeg, mais comment faire pour que Markdown ouvre un .pdf? Je n'arrive pas à obtenir la syntaxe correcte pour qu'elle ouvre mon .pdf qui se trouve dans le même répertoire que le fichier .md. Quelqu'un peut-il aider à ouvrir un fichier .pdf?
Elton

Vous pouvez trouver des solutions dans cette question: stackoverflow.com/questions/40422790/…
Oleg Pro

Réponses:


971

Mise à jour le 30 janvier 2013 , 16 mois plus tard:

GitHub Blog Post Liens relatifs dans les fichiers de balisage :

À partir d'aujourd'hui, GitHub prend en charge les liens relatifs dans les fichiers de balisage .
Vous pouvez maintenant établir un lien direct entre différents fichiers de documentation, que vous consultiez la documentation sur GitHub lui-même ou localement, à l'aide d'un rendu de balisage différent.

Vous voulez des exemples de définitions de liens et comment ils fonctionnent? Voici quelques démarques pour vous.
Au lieu d'un lien absolu:

[a link](https://github.com/user/repo/blob/branch/other_file.md)

… Vous pouvez utiliser un lien relatif:

[a relative link](other_file.md)

et nous nous assurerons qu'il est lié à user/repo/blob/branch/other_file.md.

Si vous utilisiez une solution de contournement comme [a workaround link](repo/blob/master/other_file.md), vous devrez mettre à jour votre documentation pour utiliser la nouvelle syntaxe.

Cela signifie également que votre documentation peut désormais se suffire à elle-même, sans toujours pointer vers GitHub .


Mise à jour du 20 décembre 2011:

Le problème de balisage GitHub 84 est actuellement fermé par technoweenie , avec le commentaire:

Nous avons essayé d'ajouter une <base>balise pour cela, mais cela pose des problèmes avec d'autres liens relatifs sur le site.


12 octobre 2011:

Si vous regardez la source bruteREADME.md de Markdown lui-même (!), Les chemins relatifs ne semblent pas être pris en charge.
Vous y trouverez des références comme:

[r2h]: http://github.com/github/markup/tree/master/lib/github/commands/rest2html
[r2hc]: http://github.com/github/markup/tree/master/lib/github/markups.rb#L13

1
Hmm .. Je peux créer une URL relative (essayez [link] someDir / README.md, cela fera une ancre) - mais je veux un lien relatif conscient de la branche github comme: myRepo / tree / <$ curBranch> /pathToMd.md . Je vais probablement juste ouvrir une demande de fonctionnalité avec github.com
rynop

1
Nan. Voir l'exemple complet ici github.com/rynop/testRel . Je pourrais faire un lien relatif spécifiant la branche, mais cela va à l'encontre de l'objectif de ce que j'essaie de faire en premier lieu. Si je faisais un lien entre un .md dans un sous-répertoire et un autre, je pense qu'il gérerait très bien le lien relatif. Un problème se produit lors de la liaison à partir de .md à la racine du référentiel.
rynop

2
Connexes: Pour créer un lien d'une page wiki à une autre, [Welcome](./wiki/Hello)fonctionne, où Bonjour est une autre page wiki dans le même référentiel.
Wayne Bloss

1
@wizlb Je l'ai juste essayé sans le chemin et ça marche aussi [Welcome](Hello)où Hello est une autre page wiki dans le même repo.
Mottie

2
Cela fonctionne dans les pages wiki normales, mais si vous ajoutez un fichier _Sidebar.md, il y a une différence entre la résolution des liens sur la page d'accueil du wiki et le reste des pages. J'ai tout essayé ici sans chance. Jusqu'à présent, la seule chose que j'ai trouvée est d'utiliser 2 fichiers _Sidebar.md différents et d'organiser les fichiers en sous-répertoires.
NightOwl888

93

Par exemple, vous avez un dépôt comme celui-ci:

project/
    text.md
    subpro/
       subtext.md
       subsubpro/
           subsubtext.md
       subsubpro2/
           subsubtext2.md

Le lien relatif vers subtext.mdin text.mdpourrait ressembler à ceci:

[this subtext](subpro/subtext.md)

Le lien relatif vers subsubtext.mdin text.mdpourrait ressembler à ceci:

[this subsubtext](subpro/subsubpro/subsubtext.md)

Le lien relatif vers subtext.mdin subsubtext.mdpourrait ressembler à ceci:

[this subtext](../subtext.md)

Le lien relatif vers subsubtext2.mdin subsubtext.mdpourrait ressembler à ceci:

[this subsubtext2](../subsubpro2/subsubtext2.md)

Le lien relatif vers text.mdin subsubtext.mdpourrait ressembler à ceci:

[this text](../../text.md)

1
Une chose que j'ai trouvée, les liens sont sensibles à la casse, ce à quoi je ne m'attendais pas.
Andy Wiesendanger

Et s'il y a des espaces dans mes répertoires?
Rishav

16

Au 31 janvier 2013, la démarque Github prend en charge les liens relatifs aux fichiers .

[a relative link](markdown_file.md)

Cependant, il y a quelques lacunes qui ont été discutées dans ce fil de commentaires .

Comme alternative, vous pouvez utiliser Gitdown pour construire des URL complètes vers le référentiel et même les rendre sensibles aux branches, par exemple

{"gitdown": "gitinfo", "name": "url"} // https://github.com/gajus/gitdown
{"gitdown": "gitinfo", "name": "branch"} // master

Gitdown est un préprocesseur de démarque GitHub. Il rationalise les tâches courantes associées à la maintenance d'une page de documentation pour un référentiel GitHub, par exemple la génération d'une table des matières, y compris des variables, la génération d'URL et l'obtention d'informations sur le référentiel lui-même au moment du traitement de l'entrée. Gitdown s'intègre parfaitement à vos scripts de construction.

Je suis l'auteur de la bibliothèque Gitdown.


1
@Thomas Cela fait-il partie des conditions d'utilisation de Stack Overflow? Si oui, veuillez partager un lien. Je suis curieux de connaître la motivation derrière une telle exigence.
Gajus

5
"Publiez de bonnes réponses pertinentes et si certaines (mais pas toutes) concernent votre produit ou votre site Web, ce n'est pas grave. Cependant, vous devez divulguer votre affiliation dans vos réponses." stackoverflow.com/help/behavior
Thomas

1
On pourrait penser que cela relève de la méta-information que Stack Overflow essaie d'éviter tellement, c'est-à-dire qui favorise une discussion hors sujet.
Gajus

14

GitHub pourrait faire beaucoup mieux avec un travail minimal. Voici une solution de contournement.

Je pense que tu veux quelque chose de plus

[Your Title](your-project-name/tree/master/your-subfolder)

ou pour pointer vers le fichier README lui-même

[README](your-project-name/blob/master/your-subfolder/README.md)

Bonne chance


3
oui c'est ce que je fais aujourd'hui. Je ne veux pas faire cuire les informations de branche dans le lien. Cela devrait être relatif.
rynop

8

Je voulais juste ajouter cela car aucune des solutions ci-dessus ne fonctionnait si le lien cible est un répertoire avec des espaces dans son nom. Si le lien cible est un répertoire et qu'il a de l'espace, même échapper de l'espace avec \ ne rend pas le lien sur Github. La seule solution qui a fonctionné pour moi est d'utiliser %20pour chaque espace.

par exemple: si la structure du répertoire est celle-ci

Top_dir
|-----README.md
|-----Cur_dir1
      |----Dir A
           |----README.md
      |----Dir B
           |----README.md

Pour créer un lien vers Dir AREADME.md présent dans, Top_dirvous pouvez procéder comme suit :

[Dir 1](Cur_dir1/Dir%20A)

8

Vous pouvez créer un lien vers un fichier, mais pas vers des dossiers, et gardez à l'esprit que Github ajoutera /blob/master/avant votre lien relatif (et les dossiers n'ont pas cette partie afin qu'ils ne puissent pas être liés, ni avec des <a>balises HTML ni avec un lien Markdown).

Donc, si nous avons un fichier myrepo/src/Test.java, il aura une URL comme:

https://github.com/WesternGun/myrepo/blob/master/src/Test.java

Et pour le lier dans le fichier readme, nous pouvons utiliser:

[This is a link](src/Test.java)

ou: <a href="src/Test.java">This is a link</a>.

(Je suppose, masterreprésente la masterbranche et elle diffère lorsque le fichier est dans une autre branche.)


7

Vous pouvez utiliser des URL relatives depuis la racine de votre référentiel avec <a href="">. En supposant que votre dépôt est nommé testRel, mettez ce qui suit dans testRel/README.md:

# My Project
is really really cool. My Project has a subdir named myLib, see below.

## myLib docs
see documentation:
    * <a href="testRel/myLib">myLib/</a>
    * <a href="testRel/myLib/README.md">myLib/README.md</a>

3
cette syntaxe md non valide
astroanu

6

Cette question est assez ancienne, mais elle semble toujours importante, car il n'est pas facile de mettre des références relatives de readme.md aux pages wiki sur Github.

J'ai joué un peu et ce lien relatif semble plutôt bien fonctionner:

[Your wiki page](../../wiki/your-wiki-page)

Les deux ../supprimeront /blob/master/et utiliseront votre base comme point de départ. Je n'ai pas essayé cela sur d'autres dépôts que Github, cependant (il peut y avoir des problèmes de compatibilité).


4

Je ne sais pas si je vois cette option ici. Vous pouvez simplement créer un /folderdans votre référentiel et l'utiliser directement:

[a relative link](/folder/myrelativefile.md)

Aucun blob ou arbre ou nom de référentiel n'est nécessaire, et cela fonctionne comme un charme.


1
On pourrait penser que ce serait la voie la plus évidente, mais cela ne fonctionne pas pour moi.
Kmeixner

4

Si vous voulez un lien relatif vers votre page wiki sur GitHub, utilisez ceci:

Read here: [Some other wiki page](path/to/some-other-wiki-page)

Si vous voulez un lien vers un fichier dans le référentiel, disons, pour référencer un fichier d'en-tête, et la page wiki est à la racine du wiki, utilisez ceci:

Read here: [myheader.h](../tree/master/path/to/myheader.h)

La raison du dernier est de sauter le chemin "/ wiki" avec "../", et d'aller à la branche principale dans l'arborescence du référentiel sans spécifier le nom du référentiel, qui pourrait changer à l'avenir.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.