Como faço para criar algum tipo de tabela de conteúdo no wiki do GitHub?

Se você olhar aqui: http://en.wikipedia.org/wiki/Stack_Overflow

Você notará que há uma pequena seção de "Conteúdo", se você clicar em um dos links, será direcionado para uma seção específica na página.

Como faço isso no wiki do GitHub? Com Markdown ou o que quer que eles usem?

É bem demonstrado no Índice da folha de referência do Markdown .

##### Table of Contents  
[Headers](#headers)  
[Emphasis](#emphasis)  
...snip...    
<a name="headers"/>
## Headers

Se você passar o mouse sobre um cabeçalho em um arquivo GitHub Markdown, verá um pequeno link simples à esquerda dele, você também pode usar esse link. O formato desse link é <project URL#<header name>. O <header name>deve estar todo em minúsculas.

Uma solução possível (semiautomática) é a de Eugene Kalinin github-markdown-toc. Essa ferramenta essencialmente README.mdanalisa seu arquivo e identifica os #cabeçalhos para criar um sumário.

1. Baixe o script https://github.com/ekalinin/github-markdown-toc

2. Alimente seu README.mdroteiro (conforme observado no de Eugene README.md)

   cat README.md | bash github-markdown-toc

3. Recorte e cole o TOC gerado e coloque-o no topo do seu README.mdarquivo

Observe que esta bashimplementação só funciona no Linux (pelo que posso dizer).

Como uma observação lateral, há uma implementação golang e provavelmente é mais trabalhoso para começar a trabalhar.

Uma vez que o github não pode ser usado TOCdiretamente, temos outras alternativas.

Você pode gerar TOC automaticamente por meio da ferramenta Online:

Gerar índice de sumário de GitHub Markdown ou Wiki Online

ou via ferramenta local:

github-markdown-toc

https://github.com/jonschlinkert/markdown-toc

• git clone your-repo.wiki.git(adicione o .wikidireito antes .gitde clonar o wiki
• npm i -g markdown-toc
• Insira <!-- toc -->( diferencia maiúsculas de minúsculas) na marcação do seu wiki
• markdown-toc -i my-wiki-markdown.md( -iirá editá-lo no local)
• Lucro

Atualização: acho que https://github.com/thlorenz/doctoc é mais popular agora.

Atualmente não é possível fazer isso usando a sintaxe de redução ( .md). Há uma discussão não oficial em andamento sobre a geração automática de índice TOC em arquivos de markdown renderizados, como o README.mdqual lista algumas das ideias.

No entanto, existem algumas outras soluções alternativas, como:

• Use em AsciiDocvez de acordo com a sugestão deste comentário . Por exemplo:

  :toc: macro
  :toc-title:
  :toclevels: 99
  # Title
  
  toc::[]
  
  ## A
  
  ### A2
  
  ## B
  
  ### B2
  

  Verifique o exemplo em littlebits/react-popover( README.adoc) .

• Tabela de conteúdo online gerador ( raychenon / play-table-of-contents )

• arthurhammer / github-toc - extensão do navegador que adiciona um índice aos repositórios do GitHub

Se você não estiver em posição de manter o Markdown , faça o seguinte:

• no GitHub / wiki : mude Markdown para MediaWiki . Use __TOC__sintaxe. Veja a amostra .
• no GitHub / repo : mude Markdown para AsciiDoc . Use :toc:sintaxe. Veja a demonstração .

No entanto, usando arquivos Markdown no GitHub / repo , você pode obtê-lo nas páginas do GitHub como na Wikipedia

• quando Jekyll é ativado, ele gera páginas GitHub usando Kramdown por padrão
• Kramdown vem com Table Of Content. Use {:toc}sintaxe. Veja a explicação .

Código Visual Studio

Se acontecer de você usar o Visual Studio Code , há uma extensão fácil de usar chamada Markdown All in One que pode fazer o sumário para qualquer arquivo .md em um instante.

Basta abrir a Paleta de Comandos ( Ctrl-Shift-P) ->Markdown: Create Table of Contents

A atualização automática atrapalha seu sumário editado?

Como uma dica adicional, você pode desativar as "atualizações automáticas do TOC ao salvar" usando

  "markdown.extension.toc.updateOnSave": false,

nas configurações do Visual Studio (Paleta de comandos -> Preferências: Abrir configurações (JSON)).

Você pode escolher o modo de edição "MediaWiki", que irá gerar um toc para os cabeçalhos, por exemplo

== First ==

== Second ==

Devido ao fato de que o github tem sua própria maneira de gerar atributos id = ".." em h1, h2, h3, etc ... cabeçalhos na versão html após o processamento do Markdown (por exemplo, o Bitbucket usa um padrão pouco diferente de lentidão no título dos cabeçalhos para id = "slug") é útil não reinventar a roda e usar a biblioteca que fez a engenharia reversa desse processo.

Encontrei uma biblioteca muito boa para essa tarefa chamada markdown-toc .

Para mim parece a melhor solução porque sempre instalei o node na minha máquina.

Basta executar npx remarcação-toc -i file.md .

E parece que é uma das ferramentas mais populares para essa tarefa - pelo menos no ecossistema node.js.

ls
cat <<EOF >> test.md | tee 
## Table of Contents

<!-- toc -->
- old toc 1
- old toc 2
- old toc 3
<!-- tocstop -->

## abc
This is a b c.

## xyz
This is x y z.
EOF
ls
cat test.md
npx markdown-toc -i test.md
cat test.md

resultado: