Link relativo do GitHub no arquivo Markdown


831

Existe uma maneira de criar uma âncora de URL <a>, link de dentro de um arquivo Markdown, para outro arquivo no mesmo repositório e ramificação (também conhecido como link relativo à ramificação atual)?

Por exemplo, no ramo mestre, tenho um arquivo README.md, que gostaria de fazer 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)

Isso me permitiria vincular de um arquivo .md para outro no mesmo ramo e não precisar me preocupar com qual ramo eu estou (evite ter que fazer uma URL absoluta que inclua o nome do ramo github.com).

Aqui está um exemplo de trabalho do que quero dizer:

  1. GOTO http://github.com/rynop/testRel , o link não funciona.
  2. GOTO http://github.com/rynop/testRel/blob/master/README.md , o link funciona.

Isso é esperado porque, neste ponto, o URL inicial está no ramo. Agora, como faço para pegar a ramificação atual no README.md na raiz do repositório?

Atualização : eu abri um problema no GitHub para esta solicitação de recurso.


21
Finalmente : links relativos agora são suportados! Eu atualizei minha resposta :)
VonC 31/01

Todas essas informações são boas se você estiver tentando abrir outro .md ou acessar outra página da web http / s ou html ou até páginas .jpg, .png ou jpeg, mas como você faz o Markdown abrir um .pdf? Não consigo obter a sintaxe correta para abrir meu arquivo .pdf, que está no mesmo diretório que o arquivo .md. Alguém pode ajudar a abrir um .pdf?
Elton Elton

Você pode encontrar algumas soluções nesta pergunta: stackoverflow.com/questions/40422790/…
Oleg Pro

Respostas:


970

Atualização 30 de janeiro de 2013 , 16 meses depois:

Postagem no blog do GitHub Links relativos em arquivos de marcação :

A partir de hoje, o GitHub suporta links relativos em arquivos de marcação .
Agora você pode vincular diretamente entre diferentes arquivos de documentação, seja visualizando a documentação no próprio GitHub ou localmente, usando um renderizador de marcação diferente.

Você quer exemplos de definições de links e como elas funcionam? Aqui está um Markdown para você.
Em vez de um link absoluto:

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

… Você pode usar um link relativo:

[a relative link](other_file.md)

e garantiremos que ele esteja vinculado user/repo/blob/branch/other_file.md.

Se você estava usando uma solução alternativa [a workaround link](repo/blob/master/other_file.md), precisará atualizar sua documentação para usar a nova sintaxe.

Isso também significa que sua documentação agora pode se sustentar facilmente, sem sempre apontar para o GitHub .


Atualização em 20 de dezembro de 2011:

A edição de marcação 84 do GitHub está atualmente fechada por technoweenie , com o comentário:

Tentamos adicionar uma <base>tag para isso, mas isso causa problemas com outros links relativos no site.


12 de outubro de 2011:

Se você olhar para a fonte bruta doREADME.md próprio Markdown (!), Os caminhos relativos não parecem ser suportados.
Você encontrará referências 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 .. Eu posso criar uma URL relativa (tente [link] someDir / README.md, ele criará uma âncora) - mas eu quero um link relativo com reconhecimento de ramificação do github como: myRepo / tree / <$ curBranch> /pathToMd.md . Provavelmente vou abrir uma solicitação de recurso no github.com
rynop 5/10

1
Não. Veja o exemplo completo aqui github.com/rynop/testRel . Eu poderia fazer um link relativo especificando a ramificação, mas isso anula o propósito do que estou tentando fazer em primeiro lugar. Se eu estava ligando de um .md em um subdiretório para outro, acho que ele iria lidar com link relativo muito bem. Problema ocorre ao vincular a partir de .md na raiz do repositório.
rynop

2
Relacionado: Para vincular de uma página da wiki para outra, [Welcome](./wiki/Hello)funciona, onde Hello é outra página da wiki no mesmo repositório.
Wayne Bloss

1
@ wizlb Eu apenas tentei sem o caminho e também funciona [Welcome](Hello)onde Hello é outra página wiki no mesmo repositório.
Mottie

2
Isso funciona em páginas wiki normais, mas se você adicionar um arquivo _Sidebar.md, haverá uma diferença entre a forma como os links são resolvidos na página inicial do wiki e o restante das páginas. Eu tentei de tudo aqui sem sorte. A única coisa que eu criei até agora é usar 2 arquivos _Sidebar.md diferentes e organizá-los em subdiretórios.
precisa

93

Por exemplo, você tem um repositório como o seguinte:

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

O link relativo para subtext.mdin text.mdpode ficar assim:

[this subtext](subpro/subtext.md)

O link relativo para subsubtext.mdin text.mdpode ficar assim:

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

O link relativo para subtext.mdin subsubtext.mdpode ficar assim:

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

O link relativo para subsubtext2.mdin subsubtext.mdpode ficar assim:

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

O link relativo para text.mdin subsubtext.mdpode ficar assim:

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

1
Uma coisa que eu descobri, os links diferenciam maiúsculas de minúsculas, o que eu não esperava.
Andy Wiesendanger

E se houver espaços nos meus diretórios?
Rishav 27/01

16

Em 31 de janeiro de 2013, a marcação do Github suporta links relativos a arquivos .

[a relative link](markdown_file.md)

No entanto, existem algumas deficiências que foram discutidas neste tópico de comentários .

Como alternativa, você pode usar o Gitdown para criar URLs completos para o repositório e até torná-los cientes de ramificações, por exemplo

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

Gitdown é um pré-processador de remarcação do GitHub. Ele simplifica tarefas comuns associadas à manutenção de uma página de documentação para um repositório do GitHub, por exemplo, gerar índice, incluindo variáveis, gerar URLs e obter informações sobre o próprio repositório no momento do processamento da entrada. O Gitdown se integra perfeitamente aos seus scripts de construção.

Eu sou o autor da biblioteca Gitdown.


1
@ Thomas Esta parte dos termos de uso do Stack Overflow? Se sim, compartilhe um link. Estou curioso para saber a motivação por trás de tal requisito.
Gajus

5
"Publique respostas boas e relevantes, e se algumas (mas não todas) forem sobre o seu produto ou site, tudo bem. No entanto, você deve divulgar sua afiliação nas suas respostas." stackoverflow.com/help/behavior
Thomas

1
Alguém poderia pensar que isso se enquadra na meta-informação que o Stack Overflow está tentando evitar tanto, ou seja, que promove uma discussão fora do tópico.
Gajus

14

O GitHub pode melhorar muito isso com o mínimo de trabalho. Aqui está uma solução alternativa.

Eu acho que você quer algo mais como

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

ou para apontar para o próprio README

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

Boa sorte


3
Sim, é isso que eu faço hoje. Não quero inserir as informações da filial no link. Deve ser relativo.
Rynop 31/08/2012

8

Só queria adicionar isso porque nenhuma das soluções acima funcionou se o link de destino for um diretório com espaços em seu nome. Se o link de destino for um diretório e tiver espaço, mesmo o escape de espaço com \ não renderiza o link no Github. A única solução que funcionou para mim está sendo usada %20para cada espaço.

por exemplo: se a estrutura de diretórios é essa

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

Para criar um link Dir Ano README.md presente, Top_dirvocê pode fazer isso:

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

8

Você pode vincular ao arquivo, mas não às pastas, e lembre-se de que o Github adicionará /blob/master/antes do seu link relativo (e as pastas não possuem essa parte para que não possam ser vinculadas, nem com HTML<a> tags link Markdown).

Portanto, se tivermos um arquivo myrepo/src/Test.java, ele terá um URL como:

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

E para vinculá-lo no arquivo leia-me, podemos usar:

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

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

(Eu acho, masterrepresenta o masterramo e difere quando o arquivo está em outro ramo.)


7

Você pode usar URLs relativos a partir da raiz do seu repositório <a href="">. Supondo que seu repositório seja nomeado testRel, coloque o seguinte em 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
este não é válido md sintaxe
astroanu

6

Essa pergunta é bastante antiga, mas ainda parece importante, pois não é fácil colocar referências relativas do readme.md nas páginas wiki no Github.

Eu brinquei um pouco e esse link relativo parece funcionar muito bem:

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

Os dois ../removerão /blob/master/e usarão sua base como ponto de partida. Eu ainda não tentei isso em outros repositórios que não o Github (pode haver problemas de compatibilidade).


4

Não tenho certeza se vejo esta opção aqui. Você pode simplesmente criar um /folderno seu repositório e usá-lo diretamente:

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

Nenhum nome de blob ou árvore ou repositório é necessário e funciona como um encanto.


1
Você pensaria que seria o caminho óbvio, mas não funciona para mim.
Kreixner

4

Se você deseja um link relativo à sua página wiki no GitHub, use este:

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

Se você deseja um link para um arquivo no repositório, digamos, para referenciar algum arquivo de cabeçalho, e a página wiki estiver na raiz do wiki, use este:

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

A lógica para o último é pular o caminho "/ wiki" com "../" e ir para o ramo principal na árvore do repositório sem especificar o nome do repositório, que pode mudar no futuro.

Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.