Como vincular parte do mesmo documento no Markdown?

541

Estou escrevendo um documento Markdown grande e gostaria de colocar uma espécie de sumário no início que forneça links para vários locais do documento. Como posso fazer isso?

Eu tentei usar

[a link](# MyTitle)

onde MyTitleestá um título no documento e isso não funcionou.

recipriversexclusion
fonte
1
Link para stackoverflow.com/questions/12204257/… para R Markdown (Rmd).
Etienne Low-Décarie
1
O único problema que você teve é ​​que o MyTitle não deve ser um título, mas o nome de uma âncora nesse documento (como <a name="MyTitle"> </a>). Em seguida, você poderá usar o link original em qualquer lugar do documento.
userfuser
7
A resposta aceita não é realmente relevante para a maioria das pessoas. Em vez disso, veja a segunda resposta abaixo: stackoverflow.com/a/16426829/398630
BrainSlugs83

Respostas:

37

No pandoc , se você usar a opção --tocna produção de html, um índice será produzido com links para as seções e voltará ao índice a partir dos títulos das seções. É semelhante aos outros formatos que o pandoc escreve, como LaTeX, rtf, rst, etc. Portanto, com o comando

pandoc --toc happiness.txt -o happiness.html

este pouco de remarcação:

% True Happiness

Introduction
------------

Many have posed the question of true happiness.  In this blog post we propose to
solve it.

First Attempts
--------------

The earliest attempts at attaining true happiness of course aimed at pleasure. 
Soon, though, the downside of pleasure was revealed.

produzirá isso como o corpo do html:

<h1 class="title">
    True Happiness
</h1>
<div id="TOC">
    <ul>
        <li>
            <a href="#introduction">Introduction</a>
        </li>
        <li>
            <a href="#first-attempts">First Attempts</a>
        </li>
    </ul>
</div>
<div id="introduction">
    <h2>
        <a href="#TOC">Introduction</a>
    </h2>
    <p>
        Many have posed the question of true happiness. In this blog post we propose to solve it.
    </p>
</div>
<div id="first-attempts">
    <h2>
        <a href="#TOC">First Attempts</a>
    </h2>
    <p>
        The earliest attempts at attaining true happiness of course aimed at pleasure. Soon, though, the downside of pleasure was revealed.
    </p>
</div>
aplicativo
fonte
1
Obrigado, era exatamente isso que eu precisava. Eu estava usando o Textmate para converter Markdown em HTML, mudará para pandoc.
recipriversexclusion
1
Você pode experimentar a demonstração Pandoc no Github (também há o modo emacs pandoc etc.). O tmbundle reutiliza o marcador de sintaxe específico do MultiMarkdown, então existem algumas (muito) poucas esquisitices. Além disso, muitos scripts associados são altamente personalizados - por exemplo, Contexto, não LaTeX etc. -, mas a idéia é que os usuários os alterem como bem entenderem, o que eu achei bastante simples. Provavelmente deve ser git cloneinserido no diretório tmbundle mais baixo ou mais externo, ~/Library/Application\ Support/TextMate/Bundlespara simplificar a integração.
aplicativo
2
Ele adiciona -1à primeira repetição do id, -2à segunda, etc.
aplicativa
6
Eu descobri que tinha que adicionar a opção --standalone ao comando pandoc para que ele realmente produzisse o próprio índice na saída. Sem essa opção, os cabeçalhos seriam convertidos em links para o #toc chamado anchor, mas na verdade não produziriam a âncora nomeada e a lista semelhante.
Duncan Lock
4
Isso pode responder à pergunta do OP, mas para o resto de nós que deseja saber como fazê-lo na remarcação , é bastante inútil. - A próxima resposta abaixo é muito mais útil.
BrainSlugs83
936

O Github analisa automaticamente as tags âncora dos seus cabeçalhos. Então você pode fazer o seguinte:

[Custom foo description](#foo)

# Foo

No caso acima, o Foocabeçalho gerou uma marca de âncora com o nomefoo

Nota : apenas um #para todos os tamanhos de cabeçalho, sem espaço entre #e o nome da âncora , os nomes das marcas de âncoras devem estar em minúsculas e delimitados por traços, se houver várias palavras .

[click on this link](#my-multi-word-header)

### My Multi Word Header

Atualizar

pandocTambém funciona fora da caixa .

uberllama
fonte
54
Se o seu cabeçalho contiver várias palavras, "Como este", substitua espaços por hífens na âncora [just](#like-this-one).
Mogsdad 04/04
3
Isso funciona apenas para cabeçalhos H1? Se estiver vinculando a um cabeçalho H2 (por exemplo, ## Foo), também preciso inserir dois sinais numéricos no link, por exemplo, [Foo] (## foo)? Não consigo fazer com que sua sintaxe ou a minha funcionem (com o sinal de número extra).
GrayedFox
7
@GrayedFox, se você deseja criar um link para um cabeçalho ab H2 ## Foo, tente [este é o meu link para Foo] (# foo) ... ou seja: hash único , sem espaço entre o hash e o minúsculo-kebab-case-name- do cabeçalho
Abdull 25/10
4
Como uma dica: verifique a âncora exibida ao lado do seu cabeçalho no Github para obter o respectivo link, ou seja, se ele contiver caracteres especiais, eles serão removidos automaticamente e o link correto será mostrado lá.
Alexander Pacha
2
E quando os títulos tiverem número? # 3. Terceiro ponto [Terceiro ponto] (# 3.-third.point) não funciona
Aditya
118

Experimentando, encontrei uma solução usando, <div…/>mas uma solução óbvia é colocar seu próprio ponto de ancoragem na página onde você quiser, assim:

<a name="abcde">

antes e

</a>

após a linha que você deseja 'vincular'. Em seguida, um link de remarcação como:

[link text](#abcde)

em qualquer lugar do documento leva você até lá.

A <div…/>solução insere uma divisão "fictícia" apenas para adicionar a idpropriedade, e isso é potencialmente prejudicial à estrutura da página, mas o<a name="abcde"/> solução deve ser bastante inócua.

(PS: pode ser bom colocar a âncora na linha que você deseja vincular, da seguinte maneira:

## <a name="head1">Heading One</a>

mas isso depende de como Markdown trata isso. Observo, por exemplo, que o formatador de respostas Stack Overflow está satisfeito com isso!)

Steve Powell
fonte
2
Se você fizer isso, deve estar ciente de que a div retira outra formatação de redução, como ## headers.
2rs2ts
@ user691859 Você pode elaborar? Talvez possamos atualizar uma resposta para fazê-la funcionar melhor. Eu vi o TextMate suprimir o destaque, até recuar a div, mas não há problema com a redução processada exibida em um navegador.
21411 Steve
No WriteMonkey, descobri que, se preceder qualquer texto, as <div/>várias linhas abaixo serão afetadas. Em vez disso, tenho que envolver o texto que estou vinculando em uma divcláusula de marca completa e preciso ESPECIFICAR novamente o comportamento do zero usando HTML real. Vaia.
2rs2ts
6
Isso funciona bem, obrigado. Para quem se pergunta, isso também funciona com arquivos Markdown hospedados e exibidos pelo GitHub.
Alex Dean
2
Para ser compatível com o HTML5 , eu gostaria de recomendar a substituição <a name="head1"/>por <a id="head1"/>.
binki
74

Pode ser um encadeamento desatualizado, mas para criar links internos de documentos na remarcação no Github use ...
(NOTA: #title em minúsculas)

    # Contents
     - [Specification](#specification) 
     - [Dependencies Title](#dependencies-title) 

    ## Specification
    Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

    ## Dependencies Title
    Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. Example text blah. Example text blah. 
Example text blah. Example text blah. 

Uma boa pergunta foi feita, então eu editei minha resposta;

Uma ligação interna pode ser feita a qualquer tamanho de título usando - #, ##, ###, #### eu criei um exemplo rápido abaixo ... https://github.com/aogilvie/markdownLinkTest

Aliado
fonte
No seu exemplo, as tags de link possuem apenas um #, mas os cabeçalhos aos quais eles deveriam vincular possuem dois ##; eles não deveriam ser os mesmos?
Karim Bahgat 24/02
3
Boa pergunta. A resposta é não. o # in (#dependencies-title)informa a remarcação no Github que este é um link interno. O texto a seguir pode ter qualquer tamanho de título. Aqui está um exemplo de teste que eu fiz ... https://github.com/aogilvie/markdownLinkTest
Ally
1
Isso depende do sabor da remarcação? Parece que funciona bem no editor de remarcações, mas quando salvo em html ou pdf, os IDs não são adicionados às tags apropriadas. Eu ficaria bem apenas colocando uma âncora lá, mas parece que seu método é muito mais limpo e rápido.
meteorainer
21

sim, a remarcação faz isso, mas você precisa especificar o nome âncora <a name='xyx'>.

um exemplo completo,

isso cria o link
[tasks](#tasks)

posteriormente no documento, você cria a âncora nomeada (seja como for chamada).

<a name="tasks">
   my tasks
</a>

observe que você também pode envolvê-lo no cabeçalho.

<a name="tasks">
### Agile tasks (created by developer)
</a>
davidj411
fonte
13

O manual pandoc explica como vincular seus cabeçalhos, usando o identificador deles. Não verifiquei o suporte a isso por outros analisadores, mas foi relatado que ele não funciona no github .

O identificador pode ser especificado manualmente:

## my heading text {#mht}
Some normal text here,
including a [link to the header](#mht).

ou você pode usar o identificador gerado automaticamente (neste caso #my-heading-text). Ambos são explicados em detalhes no manual pandoc .

NOTA : Isso funciona apenas na conversão para HTML , LaTex , ConTeXt , Textile ou AsciiDoc .

hoijui
fonte
9

Algumas coisas adicionais a serem lembradas, se você gosta de símbolos nos cabeçalhos que deseja navegar para ...

# What this is about


------


#### Table of Contents


- [About](#what-this-is-about)

- [&#9889; Sunopsis](#9889-tldr)

- [:gear: Grinders](#it-grinds-my-gears)

- [Attribution]


------


## &#9889; TLDR


Words for those short on time or attention.


___


## It Grinds my :gear:s


Here _`:gear:`_ is not something like &#9881; or &#9965;


___


## &#9956; Attribution


Probably to much time at a keyboard



[Attribution]: #9956-attribution

... coisas como #, ;, &, e :na posição cordas são geralmente são ignorados / listrado em vez de escapar, e também se pode usar citação ligações estilo de fazer uso rápido mais fácil.

Notas

GitHub suporta a :word:sintaxe em submissões, arquivos leia-me, etc. ver essência (de rxaviers) se usá-los for de seu interesse.

E em quase todos os lugares decimais ou hexadecimais podem ser usados ​​para navegadores modernos; as dicas da w3schools são úteis , especialmente se usar CSS ::beforeou ::afterpseudo-elementos com símbolos for o seu estilo.

Pontos bônus?

Apenas no caso de alguém estar se perguntando como as imagens e outros links dentro de um cabeçalho são analisados ​​em um id...

- [Imaged](#alt-textbadge__examplehttpsexamplecom-to-somewhere)


## [![Alt Text][badge__example]](https://example.com) To Somewhere


[badge__example]:
  https://img.shields.io/badge/Left-Right-success.svg?labelColor=brown&logo=stackexchange
  "Eeak a mouse!"

Ressalvas

A renderização do MarkDown difere de um lugar para outro, então coisas como ...

## methodName([options]) => <code>Promise</code>

... no GitHub terá um elemento com id, como ...

id="methodnameoptions--promise"

... onde o saneamento de baunilha resultaria em um id...

id="methodnameoptions-codepromisecode"

... significando que a gravação ou compilação de arquivos MarkDown a partir de modelos exige o direcionamento de uma maneira de slugifeing , ou a adição de configurações e lógica de script para as várias maneiras inteligentes que os locais gostam de limpar o texto do cabeçalho.

S0AndS0
fonte
9

Soluções universais

Esta pergunta parece ter uma resposta diferente de acordo com a implementação da remarcação.
De fato, a documentação oficial do Markdown é silenciosa sobre esse tópico.
Nesses casos, e se você quiser uma solução portátil, poderá usar HTML.

Antes de qualquer cabeçalho, ou na mesma linha de cabeçalho, defina um ID usando alguma tag HTML.
Por exemplo:<a id="Chapter1"></a>
Você verá isso no seu código, mas não no documento renderizado.

Exemplo completo:

Veja um exemplo completo (online e editável) aqui .

## Content

* [Chapter 1](#Chapter1)
* [Chapter 2](#Chapter2)

<div id="Chapter1"></div>
## Chapter 1

Some text here.  
Some text here.
Some text here.

## Chapter 2 <span id="Chapter2"><span>

Some text here.  
Some text here.
Some text here.

Para testar este exemplo, você deve adicionar um espaço extra entre a lista de conteúdo e o primeiro capítulo ou reduzir a altura da janela.
Além disso, não use espaços no nome dos IDs.

ePi272314
fonte
Pareceu legal. Tentei, dois problemas: (1). ## Chapter 1precisa de uma linha aberta acima dela. (2) O link não funciona ...
musicformellons
Ah, não funciona no plugin intellij markdown que eu usei; mas funciona no editor de marcação Macdown.
musicformellons
Ainda, testado no github: é necessária uma linha aberta acima do cabeçalho, mas funciona.
musicformellons
@musicformellons você pode tentar sem a linha de abertura, mas fechar corretamente a tag span? <br><span id="Chapter1"><span>
ePi272314
sim, funciona!
musicformellons
7

Não existe essa diretiva na especificação Markdown. Desculpa.

Nick Gerakines
fonte
Oh! Você sabe se o MultiMarkdown ou o Textile o suportam? Eu estava pensando em migrar para o MD para toda a minha documentação, mas isso é um disjuntor. Obrigado pela ajuda!
recipriversexclusion
5
O que você quer dizer com "diretiva"? Outras soluções para exatamente o problema foram postadas aqui.
Zelphir Kaltstahl,
4

O Gitlab usa GitLab Flavored Markdown (GFM)

Aqui "todos os cabeçalhos renderizados pelo Markdown recebem identificações automaticamente"

Pode-se usar o mouse para:

  • mover o mouse sobre o cabeçalho
  • mova o mouse sobre o seletor suspenso que fica visível à esquerda do cabeçalho
  • copie e salve o link usando o botão direito do mouse

    Por exemplo, no arquivo README.md, tenho o cabeçalho:

## series expansion formula of the Boettcher function

que fornece um link:

https://gitlab.com/adammajewski/parameter_external_angle/blob/master/README.md#series-expansion-formula-of-the-boettcher-function

O prefixo pode ser removido, portanto o link aqui é simplesmente

file#header

o que aqui significa:

README.md#series-expansion-formula-of-the-boettcher-function

Agora pode ser usado como:

[series expansion formula of the Boettcher function](README.md#series-expansion-formula-of-the-boettcher-function)

Também é possível fazer isso manualmente: substitua espaços por hífen.

O exemplo ao vivo está aqui

Adão
fonte
1

Usando o kramdown, parece que isso funciona bem:

[I want this to link to foo](#foo)
....
....
{: id="foo"}
### Foo are you?

Eu vejo que foi mencionado que

[foo][#foo]
....
#Foo

funciona de forma eficiente, mas o primeiro pode ser uma boa alternativa para elementos além de cabeçalhos ou cabeçalhos com várias palavras.

sadie parker
fonte
1

Desde MultiMarkdown foi mencionado como uma opção nos comentários.

No MultiMarkdown, a sintaxe para um link interno é simples.

Para qualquer cabeçalho do documento, basta fornecer o nome do cabeçalho neste formato [heading][]para criar um link interno.

Leia mais aqui: MultiMarkdown-5 Referências cruzadas .

Referências cruzadas

Um recurso frequentemente solicitado era a capacidade de o Markdown manipular automaticamente os links dentro do documento tão facilmente quanto os links externos. Para esse objetivo, adicionei a capacidade de interpretar [Some Text] [] como um link cruzado, se existir um cabeçalho chamado "Some Text".

Como exemplo, [Metadados] [] o levará a # Metadados (ou a qualquer um dos ## Metadados, ### Metadados, #### Metadados, ##### Metadados, ###### Metadados).

Como alternativa, você pode incluir um rótulo opcional de sua escolha para ajudar a desambiguar casos em que vários cabeçalhos têm o mesmo título:

### Visão geral [MultiMarkdownOverview] ##

Isso permite que você use [MultiMarkdownOverview] para se referir especificamente a esta seção, e não a outra seção chamada Visão geral. Isso funciona com cabeçalhos no estilo atx ou settext.

Se você já definiu uma âncora usando o mesmo ID usado por um cabeçalho, a âncora definida terá precedência.

Além dos cabeçalhos do documento, você pode fornecer rótulos para imagens e tabelas que também podem ser usadas para referências cruzadas.

jwpfox
fonte
0

Mais algumas rodadas no <a name="">truque:

<a id="a-link"></a> Title
------

#### <a id="a-link"></a> Title (when you wanna control the h{N} with #'s)
atraso
fonte
0

Além das respostas acima,

Ao definir a opção number_sections: trueno cabeçalho YAML:

number_sections: TRUE

O RMarkdown numerará automaticamente suas seções.

Para referenciar essas seções numeradas automaticamente, basta colocar o seguinte no seu arquivo R Markdown:

[My Section]

Onde My Sectionestá o nome da seção

Isso parece funcionar independentemente do nível da seção:

# My section

## My section

### My section

orrymr
fonte