Referência cruzada (âncora nomeada) na remarcação

512

Existe sintaxe de remarcação para o equivalente a:

Take me to <a href="#pookie">pookie</a>

... 

<a name="pookie">this is pookie</a>
Synesso
fonte

Respostas:

692
Take me to [pookie](#pookie)

deve ser a sintaxe correta da marcação para pular para o ponto de ancoragem chamado pookie.

Para inserir um ponto de ancoragem com esse nome, use HTML:

<a name="pookie"></a>

Markdown não parece se importar onde você coloca o ponto de ancoragem. Um local útil para colocá-lo é um cabeçalho. Por exemplo:

### <a name="tith"></a>This is the Heading

funciona muito bem (Eu demonstraria aqui, mas o renderizador da SO retira a âncora.)

Nota sobre tags de fechamento automático e id=versusname=

Uma versão anterior desta postagem sugeria usar <a id='tith' />, usar a sintaxe de fechamento automático para XHTML e usar o idatributo em vez de name.

O XHTML permite que qualquer tag seja 'vazia' e 'fechada automaticamente'. Ou seja, <tag />é uma abreviação de <tag></tag>, um par de tags correspondente com um corpo vazio. A maioria dos navegadores aceita XHTML, mas outros não. Para evitar problemas entre navegadores, feche a tag explicitamente usando o <tag></tag>recomendado acima.

Finalmente, o atributo name=foi descontinuado em XHTML, então usei originalmente id=, o que todos reconhecem. No entanto, o HTML5 agora cria uma variável global em JavaScript ao usar id=, e isso pode não ser necessariamente o que você deseja. Portanto, name=agora é provável que o uso seja mais amigável.

(Obrigado a Slipp Douglas por me explicar o XHTML e a nailer por apontar o efeito colateral do HTML5 - veja os comentários e a resposta do nailer para obter mais detalhes. Parece funcionar em qualquer lugar, embora esteja obsoleto no XHTML.)name=

Steve Powell
fonte
1
Você não pode ver como vincular sua demonstração de cabeçalho depois que o StackOverflow renderiza o HTML porque a renderização deles está removendo sua tag <a> . Ou seja, você não pode no StackOverflow Markdown.
Slipp D. Thompson
2
No entanto, isso funcionará em outros renderizadores Markdown mais liberais, mas você precisará de uma tag <a> de fechamento ; a tag <a> não permite fechamento automático. Além disso, encontrei meu navegador para pular o cabeçalho, a menos que a tag <a> esteja antes do conteúdo do cabeçalho. Correções feitas nos seus exemplos.
Slipp D. Thompson
2
Aguente aí, cowboy. Só porque você não tem nenhum estilo em <a>um href, não significa que ele seja fechado automaticamente. A menos que eu esteja completamente louco, os dois: test-xhtml11 e [ sln.6bitt.com/public/test-html5.htmlι(test-html5) renderizam o restante da página na tag <a>. Vá em frente e inspecione com um inspetor da web de sua escolha.
Slipp D. Thompson
4
@ Slipp: OK, eu acho que entendo, agora. Você codificou <a id="hi"/> rest of doc, mas foi tratado como <a id="hi"> rest of doc</a>. (E a análise de elementos da página também mostra isso.) Meu erro: observei os elementos exibidos e não a fonte bruta. Você acha que a resposta deve ser modificada, à luz desta observação?
21812 Steve
3
O nameatributo também cria variáveis ​​globais (consulte stackoverflow.com/questions/3434278/… ); portanto, você também pode usar o idatributo como o destino dos URLs de identificador de fragmento, conforme desejado.
Bobby Jack
92

No bitbucket.org, a solução votada não funcionaria. Em vez disso, ao usar cabeçalhos (com ##), é possível referenciá-los como âncoras, prefixando-os como # markdown-header-my-header-name, em que # markdown-header- é um prefixo implícito gerado pelo representante e o restante é o título do cabeçalho com letras minúsculas, com traços substituindo espaços.

Exemplo

## My paragraph title

produzirá uma âncora implícita como esta

#markdown-header-my-paragraph-title

O URL inteiro antes de cada referência de âncora é opcional, ou seja,

[Some text](#markdown-header-my-paragraph-title)

é equivalente a

[Some text](https://bitbucket.org/some_project/some_page#markdown-header-my-paragraph-title) 

desde que estejam na mesma página.

Fonte: https://bitbucket.org/tutorials/markdowndemo/overview (edite a fonte desse arquivo .md e veja como são feitas as âncoras).

La Muerte Peluda
fonte
1
Isso também pode acontecer. De acordo com isso: confluence.atlassian.com/bitbucket/… , o bitbucket suporta a extensão do Sumário, que pode gerar automaticamente links e âncoras com base nos cabeçalhos do documento. A extensão do sumário está documentada aqui: pythonhosted.org/Markdown/extensions/toc.html Adicione o texto "[TOC]" ao início do documento para que ele seja gerado.
Php binário
8
No Github, ## My paragraph titleproduzirá a seguinte âncora user-content-my-paragraph-title, para que você possa referenciá-la com [Some text] (# user-content-my-paragraph-title). No entanto, não encontrei documentação oficial para isso.
Toto_tico
Isso também me ajudou no Bitbucket - funciona como um encanto.
22816 Scott Byers
1
Esta é uma informação útil; obrigado. No entanto, os renderizadores de markdown sem as extensões não geram essas âncoras para você, e os nomes de cabeçalho em conflito resultarão em IDs de âncora em conflito (ou algum truque de distinção inútil, como número é suficiente). Os IDs de âncora explícitos são melhores, mais controláveis, não estão sujeitos a alterações aleatórias devido a atualizações de texto (veja o truque acima) e são úteis para ancorar mais do que apenas cabeçalhos. Ambas as técnicas são necessárias em geral.
21416 Steve
No stackedit.io [linky](#header) havia uma âncora suficiente e também funcionava quando publicado no Gist.
Felipe Alvarez
67

Use a name. Usar um idnão é necessário no HTML 5 e criará variáveis ​​globais no seu JavaScript

Consulte a especificação HTML 5, 5.9.8 Navegando para um identificador de fragmento - ambos ide namesão usados.

É importante saber que a maioria dos navegadores ainda transforma IDs em variáveis ​​globais . Aqui está um teste rápido . O uso de um nameevita a criação de globais e quaisquer conflitos que possam resultar.

Exemplo usando um nome:

Take me to [pookie](#pookie)

E a âncora de destino:

### <a name="pookie"></a>Some heading
mikemaccana
fonte
5
Downvoting. O argumento da variável global é fraco, pois você não deve definir (diretamente) variáveis ​​globais em seu JS de qualquer maneira, portanto, nenhum conflito ocorrerá. Além disso, a semântica de namee idé diferente.
Marnen Laibow-Koser
9
@ MarnenLaibow-Koser Ninguém está discutindo a definição de variáveis ​​globais em JS. Criar um ID em HTML cria uma janela global, algo na maioria dos navegadores.
Mikemaccana 12/09/14
14
@ MarnenLaibow-Koser Muitas bibliotecas (por exemplo, não o seu próprio JS, mas o de outra pessoa) usam um único global - por exemplo, fineuploader. Se você criar um elemento com um ID de fineuploader, não poderá usar o fineuploadermódulo. Evitar a criação de globais desnecessários ajuda a evitar esses conflitos.
Mikemaccana # 14/14
5
Eu estaria interessado em executar alguns testes desse caso e descobrir qual deles tem precedência. Aprecio a questão teórica, mas em anos de desenvolvimento do lado do cliente, nunca tive um ID quebrado de qualquer JS do lado do cliente (desde que o HTML fosse válido). Continuarei a usá-los quando eles forem semanticamente apropriados até encontrar problemas reais.
Marnen Laibow-Koser
2
@ MarnenLaibow-Koser I (e muitos outros) tiveram IDs HTML quebrando o JavaScript real - há um exemplo muito prático no comentário ao qual você está respondendo! Existem muitos guias de estilo e empresas que sempre usam aulas, mesmo para singletons, e é por isso.
Mikemaccana
17

A âncora de Markdown suporta o hashmark; portanto, um link para uma âncora na página seria simplesmente[Pookie](#pookie)

A geração da âncora não é realmente suportada no Gruber Markdown, mas em outras implementações, como o Markdown Extra .

No Markdown Extra, o ID da âncora é anexado a um cabeçalho ou subtítulo com {#pookie}.

O Markdown com sabor do Github nas páginas do repositório Git (mas não no Gists) gera automaticamente âncoras com várias tags de marcação em todos os cabeçalhos (h1, h2, h3 etc.), incluindo:

  • id="user-content-HEADERTEXT"
  • class="anchor"
  • href="#HEADERTEXT"
  • aria-hidden="true" (isto é para um ícone de link svg que é exibido na passagem do mouse)

Excluindo o ícone ária / svg, quando se escreve:

  • # Header Title

O Github gera:

  • <h1><a id="user-content-header-title" class="anchor" href="#header-title">Header Title</a></h1>

Portanto, não é necessário fazer nada para criar os links do cabeçalho e sempre pode-se vincular a eles com:

  • Link para o [Header Title](#header-title)
jeffmcneill
fonte
16

Não há sintaxe prontamente disponível para fazer isso na sintaxe original do Markdown, mas o Markdown Extra fornece um meio de pelo menos atribuir IDs aos cabeçalhos - aos quais você pode vincular facilmente. Observe também que você pode usar HTML regular no Markdown e no Markdown Extra e que o nameatributo foi substituído pelo idatributo nas versões mais recentes do HTML.

Vocês
fonte
9

Para quem está procurando uma solução para esse problema no GitBook. Foi assim que eu fiz funcionar (no GitBook). Você precisa marcar seu cabeçalho explicitamente, assim:

# My Anchored Heading {#my-anchor}

Em seguida, vincule a esta âncora como esta

[link to my anchored heading](#my-anchor)

Solução e exemplos adicionais podem ser encontrados aqui: https://seadude.gitbooks.io/learn-gitbook/

keyoxy
fonte
obrigado! isso funciona! isso deve ser votado!
Dexter
Melhor resposta! Thanks
invis
7

Tarde para a festa, mas acho que essa adição pode ser útil para as pessoas que trabalham rmarkdown. Normarkdown há suporte embutido para referências a cabeçalhos no documento.

Qualquer cabeçalho definido por

# Header

pode ser referenciado por

get me back to that [header](#header)

A seguir está um .rmdarquivo autônomo mínimo que mostra esse comportamento. Pode ser tricotado em .pdfe .html.

---
title: "references in rmarkdown"
output:
  html_document: default
  pdf_document: default
---

# Header

Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. Write some more text. 

Go back to that [header](#header).
symbolrush
fonte
4

Usando o Markdown mais recente, você poderá usar a seguinte sintaxe:

[](){:name='anchorName'}

Isso deve criar o seguinte HTML:

<a name="anchorName"></a>

Se você deseja que a âncora tenha texto, basta adicioná-lo entre colchetes:

[Some Text](){:name='anchorName'}

Ryan McGuinness
fonte
Parece que apenas Marukuconhece essa sintaxe. Veja a marca de babel.
Ulysse BN
3

Para os geradores de redução mais comuns. Você tem uma âncora auto gerada simples em cada cabeçalho. Por exemplo, com o pandoc , a âncora gerada será uma lesma de caso de kebab do seu cabeçalho.

 echo "# Hello, world\!" | pandoc
 # => <h1 id="hello-world">Hello, world!</h1>

Dependendo do analisador de remarcação usado, a âncora pode mudar (pegue o exemplo das respostas de SymbolRush e La muerte Peluda, elas são diferentes!). Veja esta marca de rótulo onde você pode ver as âncoras geradas, dependendo da sua implementação de redução .

Ulysse BN
fonte