TOC automático na remarcação com sabor do github

É possível gerar um sumário automático usando o Github Flavored Markdown ?

Eu criei duas opções para gerar um toc para a remarcação com sabor do github:

A Ferramenta de Linha de Comando DocToc ( origem ) requer node.js

npm install doctoc

npx doctoc . para adicionar um índice a todos os arquivos de remarcação nos diretórios atual e em todos os subdiretórios.

DocToc WebApp

Se você quiser experimentá-lo online primeiro, acesse o site doctoc , cole o link da página de remarcação e ele gerará uma tabela de conteúdo que você pode inserir na parte superior do arquivo de remarcação.

Wikis e âncoras do Github

Como Matthew Flaschen apontou nos comentários abaixo, para suas páginas wiki o GitHub anteriormente não gerou as âncoras das quais doctocdepende.

ATUALIZAÇÃO: No entanto, eles corrigiram esse problema .

As páginas do GitHub (que são basicamente um wrapper para Jekyll) parecem usar o kramdown , que implementa todo o Maruku , e, portanto, tem suporte para um índice gerado automaticamente através de um tocatributo:

* auto-gen TOC:
{:toc}

A primeira linha apenas inicia uma lista não ordenada e é realmente descartada.

Isso resulta em um conjunto aninhado de listas não ordenadas, usando os cabeçalhos no documento.

Nota: isso deve funcionar para as páginas do GitHub, não para o GitM Flavored Markdown (GFM), conforme usado nos comentários ou nas páginas da wiki. AFAIK não existe uma solução para isso.

Se você editar arquivos Markdown com o Vim, poderá experimentar este plugin vim-markdown-toc .

O uso é simples, basta mover o cursor para o local que você deseja anexar e executar :GenTocGFM, pronto!

Imagens:

Recursos:

1. Gere toc para arquivos Markdown. (Suporte ao GitHub com sabor de Markdown e Redcarpet)

2. Atualize o toc existente.

3. Atualização automática toc ao salvar.

Não é automático, mas usa expressões regulares do Notepad ++:

Substitua todos os primeiros a cada segundo (remove todas as linhas que não têm cabeçalhos)

^##(#?)(#?)(.*?)$(.|\r|\n)*?(?=^##|\z)
-\1\2 [\3](#\3)\n

Então (converte os cabeçalhos III em espaços)

-##
        -

Então (converte os cabeçalhos II em espaços)

-#
    -

Em seguida (remova os caracteres não utilizados no início e no final do título do link)

\[ *((?:(?![ .:#!\?;]*\])[^#])*)[ #:!\?;]*\]
[\1]

Em seguida (converta os últimos tokens em minúsculas e trace em vez de espaços)

\]([^ \r\n]*) ([^\r\n ]*)
]\L\1-\2

Remova libras finais não utilizadas e traços iniciais:

(?:()[-:;!\?#]+$|(\]#)-)
\1\2

Remova caracteres inúteis nos links:

(\].*?)(?:\(|\))
\1

E, finalmente, adicione parênteses nos links finais:

\](?!\()(.*?)$
\]\(\1\)

E voilà! Você pode até colocar isso em uma macro global se repetir o tempo suficiente.

Não é possível, exceto pelas soluções alternativas propostas.

I proposta de extensão Kramdown TOC e outras possibilidades de [email protected] e Steven! Ragnarök respondeu com o habitual:

Obrigado pela sugestão e links. Vou adicioná-lo à nossa lista de solicitações de recursos internos para a equipe ver.

Vamos votar esta questão até que ela aconteça.

Outra solução alternativa é usar o Asciidoc em vez do Markdown, que processa os TOCs . Hoje, mudei para essa abordagem para o meu conteúdo.

O Github Flavored Markdown usa o RedCarpet como seu mecanismo de Markdown. No repositório RedCarpet :

: with_toc_data - adicione âncoras HTML a cada cabeçalho no HTML de saída, para permitir o vínculo com cada seção.

Parece que você precisaria chegar ao nível do renderizador para definir esse sinalizador, o que não é possível no Github, obviamente. No entanto, na atualização mais recente do Github Pages, parece que a ancoragem automática está ativada para cabeçalhos, criando cabeçalhos vinculáveis. Não é exatamente o que você deseja, mas pode ajudar a criar um sumário para o seu documento um pouco mais fácil (embora manualmente).

Uma maneira muito conveniente de obter um índice para um arquivo de mardown ao trabalhar com o Visual Studio Code é a extensão Markdown-TOC .

Ele pode adicionar um toc aos arquivos existentes e até mesmo mantê-lo atualizado para salvar.

É possível gerar uma página da web automaticamente com http://documentup.com/ a partir do README.mdarquivo Não está criando um sumário, mas para muitos pode resolver o motivo de querer criar um sumário.

Outra alternativa ao Documentup é o Flatdoc: http://ricostacruz.com/flatdoc/

Gitdown é um pré-processador de remarcação para o Github.

Usando o Gitdown, você pode:

• Gerar sumário
• Encontre URLs mortos e identificadores de fragmentos
• Incluir variáveis
• Incluir arquivos
• Obter tamanho do arquivo
• Gerar emblemas
• Data de impressão
• Imprimir informações sobre o próprio repositório

O Gitdown simplifica tarefas comuns associadas à manutenção de uma página de documentação para um repositório GitHub.

Usá-lo é simples:

var Gitdown = require('gitdown');

Gitdown
    // Gitdown flavored markdown.
    .read('.gitdown/README.md')
    // GitHub compatible markdown.
    .write('README.md');

Você pode tê-lo como um script separado ou como parte da rotina de criação de scripts (como Gulp ).

Use coryfklein / doctoc , um fork do thlorenz / doctoc que não adicione " gerado com o DocToc " a todos os índices.

npm install -g coryfklein/doctoc

Meu colega @schmiedc e eu criamos um script GreaseMonkey que instala um novo TOCbotão à esquerda do h1botão que usa o excelentemarkdown-js biblioteca para adicionar / atualizar um índice.

A vantagem sobre soluções como o doctoc é que ele se integra ao editor de wiki do GitHub e não precisa que os usuários trabalhem em sua linha de comando (e exige que os usuários instalem ferramentas como node.js ). No Chrome, ele funciona arrastando e soltando na página Extensões. No Firefox, você precisará instalar a extensão GreaseMonkey.

Ele funcionará com remarcações simples (ou seja, não manipula blocos de código corretamente, pois é uma extensão do GitHub para remarcações). Contribuições são bem-vindas.

Esta não é uma resposta direta a esta pergunta, pois muitas pessoas forneceram soluções alternativas. Eu não acho que a geração de um sumário tenha sido oficialmente suportada pelo Github até o momento. Se você deseja que o GitHub renderize um Sumário nas páginas de visualização do GFM automaticamente, participe da discussão sobre o problema oficial de solicitação de recurso .

Atualmente, não é possível usar a sintaxe de remarcação (consulte a discussão em andamento no GitHub ); no entanto, você pode usar algumas ferramentas externas, como:

• Gerador de tabela de conteúdo on-line ( raychenon / play-table-of-contents )
• arthurhammer / github-toc - extensão do navegador que adiciona um índice aos repositórios do GitHub

Como alternativa, use em AsciiDocvez (por exemplo README.adoc), por exemplo

:toc: macro
:toc-title:
:toclevels: 99
# Title

## A

### A2

## B

### B2

como sugerido neste comentário . Confira a demonstração aqui .

Para o Texteditor Atom do Github, confira este incrível plugin (ou "pacote" no Atom-lingo), que gera "TOC (índice) das manchetes dos arquivos analisados" :

markdown-toc

Depois de instalado como pacote Atom, você pode usar o atalho ctrl-alt-c para inserir um sumário com base na sua estrutura de markdown-doc na posição atual do cursor ...

Imagens:

Atom Keybindings

markdown-toc fornece as seguintes combinações de teclas padrão para controlar o plug-in no Atom:

• ctrl-alt-c => criar sumário na posição do cursor
• ctrl-alt-u => atualizar o sumário
• ctrl-alt-r => excluir sumário

Recursos de plug-in (do README do projeto)

• Ligação automática através de etiquetas de ancoragem, por exemplo # A 1→#a-1
• Controle de profundidade [1-6] com depthFrom:1edepthTo:6
• Ativar ou desativar links com withLinks:1
• Atualizar lista ao salvar com updateOnSave:1
• Use a lista ordenada (1. ..., 2. ...) com orderedList:0

Aqui está um script de shell que juntei hoje para isso. Pode ser necessário ajustá-lo para suas necessidades, mas deve ser um bom ponto de partida.

cat README.md \
    | sed -e '/```/ r pf' -e '/```/,/```/d' \
    | grep "^#" \
    | tail -n +2 \
    | tr -d '`' \
    | sed 's/# \([a-zA-Z0-9`. -]\+\)/- [\1](#\L\1)/' \
    | awk -F'(' '{for(i=2;i<=NF;i++)if(i==2)gsub(" ","-",$i);}1' OFS='(' \
    | sed 's/^####/      /' \
    | sed 's/^###/    /' \
    | sed 's/^##/  /' \
    | sed 's/^#//'

Se alguém souber a melhor maneira de fazer essas # substituições finais, adicione um comentário. Eu tentei várias coisas e não estava feliz com nada, então eu apenas a forcei.

Agora há uma ação do GitHub realizando isso:

https://github.com/marketplace/actions/toc-generator

1. Especifique a localização do sumário (opção), por exemplo README.md

<!-- START doctoc -->
<!-- END doctoc -->

2. Configuração do fluxo de trabalho, por exemplo .github/workflows/toc.yml

on: push
name: TOC Generator
jobs:
  generateTOC:
    name: TOC Generator
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2

A maioria das outras respostas requer a instalação de alguma ferramenta. Encontrei uma solução on-line rápida e fácil https://imthenachoman.github.io/nGitHubTOC .

Para qualquer entrada de remarcação, gera uma tabela de saída de conteúdo. Você pode especificar o nível mínimo e máximo do cabeçalho.

O código fonte está localizado em https://github.com/imthenachoman/nGitHubTOC