Enlace relativo de GitHub en el archivo Markdown


832

¿Hay alguna manera de crear un ancla de URL <a>, un enlace desde un archivo Markdown a otro archivo dentro del mismo repositorio y rama (también conocido como un enlace relativo a la rama actual)?

Por ejemplo, en la rama maestra tengo un archivo README.md, que me gustaría hacer algo como:

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

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

Esto me permitiría vincular de un .md a otro dentro de la misma rama y no tener que preocuparme por la rama en la que estoy (evite tener que hacer una URL absoluta que incluya el nombre de la rama github.com).

Aquí hay un ejemplo práctico de lo que quiero decir:

  1. GOTO http://github.com/rynop/testRel , el enlace no funciona.
  2. GOTO http://github.com/rynop/testRel/blob/master/README.md , enlace funciona.

Esto se espera porque en este punto la URL de inicio está en la rama. Ahora, ¿cómo consigo que recoja la rama actual en README.md en la raíz del repositorio?

Actualización : abrí un problema contra GitHub para esta solicitud de función.


21
Finalmente : ¡los enlaces relativos ahora son compatibles! He actualizado mi respuesta :)
VonC

Esta es toda una buena información si está intentando abrir otro .md o ir a otra página web http / s o html o incluso .jpg, .png o jpeg, pero ¿cómo hace que Markdown abra un .pdf? No puedo obtener la sintaxis correcta para que abra mi .pdf que está en el mismo directorio que el archivo .md. ¿Alguien puede ayudar a abrir un .pdf?
Elton

Puede encontrar algunas soluciones en esta pregunta: stackoverflow.com/questions/40422790/…
Oleg Pro

Respuestas:


971

Actualización 30 de enero de 2013 , 16 meses después:

Publicación en el blog de GitHub Enlaces relativos en archivos de marcado :

A partir de hoy, GitHub admite enlaces relativos en archivos de marcado .
Ahora puede vincular directamente entre diferentes archivos de documentación, ya sea que vea la documentación en GitHub o localmente, utilizando un procesador de marcado diferente.

¿Quieres ejemplos de definiciones de enlaces y cómo funcionan? Aquí hay un Markdown para ti.
En lugar de un enlace absoluto:

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

... puedes usar un enlace relativo:

[a relative link](other_file.md)

y nos aseguraremos de que se vincula a user/repo/blob/branch/other_file.md.

Si estaba utilizando una solución alternativa como [a workaround link](repo/blob/master/other_file.md), tendrá que actualizar su documentación para usar la nueva sintaxis.

Esto también significa que su documentación ahora puede sostenerse fácilmente por sí misma, sin siempre apuntar a GitHub .


Actualización 20 de diciembre de 2011:

El problema 84 del marcado de GitHub está actualmente cerrado por technoweenie , con el comentario:

Intentamos agregar una <base>etiqueta para esto, pero causa problemas con otros enlaces relativos en el sitio.


12 de octubre de 2011:

Si observa la fuente sin procesarREADME.md de Markdown (!), Las rutas relativas no parecen ser compatibles.
Encontrará referencias como:

[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 .. Puedo hacer una URL relativa (prueba [link] someDir / README.md, hará un ancla) - pero quiero un enlace relativo consciente de la rama github como: myRepo / tree / <$ curBranch> /pathToMd.md . Probablemente abriré una solicitud de función con github.com
rynop

1
no Vea el ejemplo completo aquí github.com/rynop/testRel . Podría hacer un enlace relativo que especifique la rama, pero eso frustra el propósito de lo que estoy tratando de hacer en primer lugar. Si estaba enlazando desde un .md en un subdirectorio a otro, creo que manejaría bien el enlace relativo. El problema ocurre cuando se vincula desde .md en la raíz del repositorio.
rynop

2
Relacionado: para vincular de una página wiki a otra, [Welcome](./wiki/Hello)funciona, donde Hello es otra página wiki en el mismo repositorio.
Wayne Bloss

1
@wizlb Lo probé sin la ruta y también funciona [Welcome](Hello)donde Hello es otra página wiki en el mismo repositorio.
Mottie

2
Esto funciona en las páginas wiki normales, pero si agrega un archivo _Sidebar.md, hay una diferencia entre la forma en que los enlaces se resuelven en la página de inicio wiki que el resto de las páginas. Intenté todo aquí sin suerte. Lo único que se me ocurrió hasta ahora es usar 2 archivos _Sidebar.md diferentes y organizar los archivos en subdirectorios.
NightOwl888

93

Por ejemplo, tiene un repositorio como el siguiente:

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

El enlace relativo a subtext.mdin text.mdpodría verse así:

[this subtext](subpro/subtext.md)

El enlace relativo a subsubtext.mdin text.mdpodría verse así:

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

El enlace relativo a subtext.mdin subsubtext.mdpodría verse así:

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

El enlace relativo a subsubtext2.mdin subsubtext.mdpodría verse así:

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

El enlace relativo a text.mdin subsubtext.mdpodría verse así:

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

1
Una cosa que he encontrado es que los enlaces distinguen entre mayúsculas y minúsculas, algo que no esperaba.
Andy Wiesendanger

¿Qué pasa si hay espacios en mis directorios?
Rishav

16

A partir del 31 de enero de 2013, Github Markdown admite enlaces relativos a archivos .

[a relative link](markdown_file.md)

Sin embargo, hay algunas deficiencias que se han discutido en este hilo de comentarios .

Como alternativa, puede usar Gitdown para construir URL completas para el repositorio e incluso hacer que se ramifiquen, p. Ej.

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

Gitdown es un preprocesador de rebajas de GitHub. Agiliza las tareas comunes asociadas con el mantenimiento de una página de documentación para un repositorio de GitHub, por ejemplo, generar una tabla de contenido, incluidas variables, generar URL y obtener información sobre el repositorio en sí en el momento de procesar la entrada. Gitdown se integra perfectamente con sus scripts de construcción.

Soy el autor de la biblioteca Gitdown.


1
@Thomas ¿Es esto parte de los términos de uso de Stack Overflow? En caso afirmativo, comparta un enlace. Tengo curiosidad por saber la motivación detrás de tal requisito.
Gajus

55
"Publique respuestas buenas y relevantes, y si algunas (pero no todas) son sobre su producto o sitio web, está bien. Sin embargo, debe revelar su afiliación en sus respuestas". stackoverflow.com/help/behavior
Thomas

1
Uno pensaría que esto cae dentro de la metainformación que Stack Overflow está tratando de evitar tanto, es decir, que promueve una discusión fuera del tema.
Gajus

14

GitHub podría hacer esto mucho mejor con un trabajo mínimo. Aquí hay una solución alternativa.

Creo que quieres algo más como

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

o para señalar el README mismo

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

Buena suerte


3
Sí, esto es lo que hago hoy. No quiero hornear la información de la rama en el enlace. Debería ser relativo.
rynop

8

Solo quería agregar esto porque ninguna de las soluciones anteriores funcionó si el enlace de destino es un directorio con espacios en su nombre. Si el enlace de destino es un directorio y tiene espacio, incluso escapar del espacio con \ no representa el enlace en Github. La única solución que me funcionó es usar %20para cada espacio.

por ejemplo: si la estructura del directorio es esto

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

Para hacer un enlace a Dir AREADME.md presente en Top_dirusted, puede hacer esto:

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

8

Puede vincular a un archivo, pero no a carpetas, y tenga en cuenta que Github agregará /blob/master/antes de su vínculo relativo (y las carpetas carecen de esa parte, por lo que no pueden vincularse, ni con <a>etiquetas HTML ni con enlace de Markdown).

Entonces, si tenemos un archivo myrepo/src/Test.java, tendrá una URL como:

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

Y para vincularlo en el archivo Léame, podemos usar:

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

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

(Supongo que masterrepresenta la masterrama y difiere cuando el archivo está en otra rama).


7

Puede usar URL relativas desde la raíz de su repositorio con <a href="">. Suponiendo que su repositorio se llama testRel, ponga lo siguiente en 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
esta sintaxis de md no válida
astroanu

6

Esta pregunta es bastante antigua, pero aún parece importante, ya que no es fácil poner referencias relativas de readme.md a páginas wiki en Github.

Jugué un poco y este vínculo relativo parece funcionar bastante bien:

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

Los dos ../eliminarán /blob/master/y usarán su base como punto de partida. Sin embargo, no he probado esto en otros repositorios que no sean Github (puede haber problemas de compatibilidad).


4

No estoy seguro si veo esta opción aquí. Puede crear un /folderen su repositorio y usarlo directamente:

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

No se necesita un nombre de blob o árbol o repositorio, y funciona de maravilla.


1
Pensarías que sería la forma obvia, pero no funciona para mí.
Kmeixner

4

Si desea un enlace relativo a su página wiki en GitHub, use esto:

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

Si desea un enlace a un archivo en el repositorio, digamos, para hacer referencia a algún archivo de encabezado, y la página wiki está en la raíz de la wiki, use esto:

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

La razón de esto es omitir la ruta "/ wiki" con "../" e ir a la rama maestra en el árbol del repositorio sin especificar el nombre del repositorio, que puede cambiar en el futuro.

Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.