Como criar link em Markdown com o texto que você escolher
Quer exibir Guia de instalação em vez de uma URL comprida? Use o formato Com texto. O nome fica entre colchetes e o destino, entre parênteses. O gerador monta essa sintaxe enquanto você preenche os campos.
Se precisar consultar outras regras de formatação, veja o guia rápido de sintaxe Markdown.
Escreva o texto e cole a URL
Em Texto do link, diga o que a pessoa vai encontrar: Documentação, Ver demonstração ou Guia de instalação. Em URL ou caminho de destino, cole o endereço. O título ao passar o mouse é opcional e não substitui o texto visível.
Confira o Markdown e a prévia
Para o texto Guia de instalação e a URL https://example.com/docs, o resultado é [Guia de instalação](<https://example.com/docs>). A prévia mostra a aparência do link; os sinais < > fazem parte do código gerado.
Copie e cole no documento
Clique em Copiar Markdown e cole o código no README ou no editor de Markdown. Para revisar o documento inteiro, use a prévia de Markdown em tempo real. Depois de salvar, confira o link na plataforma em que o documento será lido, principalmente se o destino for um arquivo do projeto ou uma seção.
Como colocar link no README do GitHub
Quem abre o README precisa encontrar o próximo passo: testar o projeto, ler a documentação ou saber como contribuir. Use um texto que deixe esse destino claro. Abaixo, cada exemplo corresponde ao formato Com texto, sem título opcional.
Para apontar para outro arquivo do repositório, informe o caminho a partir da pasta do README. Se os dois estiverem na raiz, ./CONTRIBUTING.md aponta para o guia de contribuição. Se o README estiver em outra pasta, ajuste o caminho antes de gerar. A documentação do GitHub sobre links relativos explica como esses caminhos são resolvidos no repositório.
| O que o leitor procura | Destino informado | Código para colar no README |
|---|---|---|
| Testar o projeto | https://example.com/demo | [Ver demonstração](<https://example.com/demo>) |
| Consultar a documentação | https://example.com/docs | [Documentação](<https://example.com/docs>) |
| Ler as instruções de instalação | ./docs/instalacao.md | [Guia de instalação](<./docs/instalacao.md>) |
| Contribuir com o repositório | ./CONTRIBUTING.md | [Como contribuir](<./CONTRIBUTING.md>) |
Links para seções com acentos e títulos repetidos no GitHub
No GitHub, os acentos de títulos como Instalação e Visão geral são mantidos nas âncoras. Os espaços viram hífens, e um título repetido recebe um sufixo para distinguir seu destino. A documentação do GitHub sobre links de seção descreve essas regras e como copiar a âncora pelo ícone ao lado do título.
No exemplo abaixo, os três títulos aparecem nesta ordem no mesmo README, sem outras seções com essas âncoras. Escolha Com texto, informe a âncora no campo de destino e escreva o texto do link. O gerador usa o destino informado; não calcula a âncora a partir do título.
Se você renomear ou reorganizar as seções, confira novamente as âncoras no GitHub. Outros editores podem seguir regras diferentes. Para criar uma lista de links a partir dos títulos do documento, use o gerador de sumário Markdown.
| Título no README, na ordem do arquivo | Âncora no GitHub | Código gerado |
|---|---|---|
## Instalação | #instalação | [Instalação](<#instalação>) |
## Visão geral | #visão-geral | [Visão geral](<#visão-geral>) |
## Instalação | #instalação-1 | [Instalação alternativa](<#instalação-1>) |
Link Markdown não funciona? Confira espaços, parênteses e caminhos
Um código bem formado ainda pode apontar para o lugar errado. O gerador confere o formato do destino, mas não verifica se a página, o arquivo ou a seção existe. Se o link no README não funciona, confira primeiro a pasta de origem, o nome do arquivo e as letras maiúsculas e minúsculas.
Para um link com espaço em Markdown, cole o caminho completo: o gerador troca os espaços por %20. Nos formatos Com texto, Por referência e Imagem, ele delimita o destino com < >, inclusive quando há parênteses no endereço. Colchetes no texto do link recebem uma barra de escape.
A forma [texto](<destino>) é válida na especificação CommonMark para links. Os sinais < > delimitam o destino no código e não aparecem no texto do link renderizado.
Nos caminhos relativos, use ./ para partir da pasta atual ou ../ para subir uma pasta. Caminhos que começam com / também são aceitos; a plataforma em que você publica define qual raiz será usada. A prévia desta página não reproduz as pastas do seu repositório.
| Situação | Destino informado | Código gerado |
|---|---|---|
| Nome de arquivo com espaço | ./docs/guia inicial.md | [Guia inicial](<./docs/guia%20inicial.md>) |
| URL com parênteses | https://example.com/guia(2) | [Guia revisado](<https://example.com/guia(2)>) |
Qual formato usar: com texto, por referência ou automático?
Escolha pelo que você precisa colocar no documento. O modo Imagem tem outra função: inserir uma imagem, em vez de criar um link de texto.
Com texto: para dar um nome ao destino
Use em links como Documentação ou Portfólio. Também aceita âncoras, caminhos de arquivos, e-mails e telefones com tel:. Por exemplo, [email protected] vira [Fale com a equipe](<mailto:[email protected]>) se esse for o texto informado.
Por referência: para separar o endereço do texto
Um link de referência Markdown facilita a leitura do código quando há muitos endereços no documento. O gerador entrega duas partes: [Documentação][docs] e, após uma linha em branco, [docs]: <https://example.com/docs>. Cole as duas no mesmo arquivo. Você pode reutilizar [Documentação][docs] ao longo do texto e manter uma única definição.
Link automático: para mostrar o próprio endereço
Se não precisa de texto personalizado, informe o site ou e-mail. Uma URL como https://example.com/docs gera <https://example.com/docs>. Esse formato não aceita caminhos relativos, âncoras ou telefones com tel:.
Imagem: para inserir uma captura de tela ou um diagrama
Preencha o texto alternativo e o endereço da imagem. Com Tela do projeto e ./imagens/tela.png, a saída é . O texto alternativo descreve a imagem; esse código, sozinho, não a transforma em um link clicável.
Como gerar links Markdown em lote
Vai montar uma lista de materiais de estudo ou reunir os links de um projeto? Selecione Em lote, escolha o formato e cole uma entrada por linha. Em Com texto, Por referência e Imagem, o separador entre os campos é |.
Se houver um problema, o aviso mostra o número da linha. A cópia inclui somente as entradas válidas: corrija os avisos para não deixar nenhum item de fora. No formato Por referência, cada entrada do lote precisa ter um ID diferente, mesmo que você pretenda reutilizar uma referência depois no documento.
Exemplo em Com texto, sem título opcional. Cole estas duas linhas no campo do lote:Documentação | https://example.com/docsInstalação | ./docs/instalacao.md
O resultado copiado reúne os dois links, um por linha:[Documentação](<https://example.com/docs>)[Instalação](<./docs/instalacao.md>)
| Formato escolhido | Exemplo de entrada | Ordem dos campos |
|---|---|---|
| Com texto | Documentação | https://example.com/docs | Guia do projeto | Texto | destino | título opcional |
| Por referência | Documentação | /docs | docs | Guia do projeto | Texto | destino | ID da referência | título opcional |
| Link automático | [email protected] | Um site ou e-mail por linha, sem separador |
| Imagem | Tela do projeto | ./imagens/tela.png | Visão geral | Texto alternativo | destino da imagem | título opcional |