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.

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>

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 .

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!)

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

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>

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 .

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)

- [⚡ Sunopsis](#9889-tldr)

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

- [Attribution]


------


## ⚡ TLDR


Words for those short on time or attention.


___


## It Grinds my :gear:s


Here _`:gear:`_ is not something like ⚙ or ⛭


___


## ⛤ 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.

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.

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

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

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.

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.

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)

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