Markdown para criar páginas e sumário?


358

Comecei a usar o markdown para fazer anotações.

Eu uso marcado para ver minhas notas de remarcação e suas lindas.

Mas, à medida que minhas anotações ficam mais longas, acho difícil encontrar o que quero.

Eu sei que o markdown pode criar tabelas, mas ele é capaz de criar um índice, que pula para seções ou define seções da página no markdown?

Como alternativa, existem leitores / editores de descontos que poderiam fazer essas coisas. Pesquisa seria um bom recurso para ter também.

Em suma, quero torná-la minha ferramenta incrível de anotações e funciona como escrever um livro etc.


2
se você quiser usar uma ferramenta javascript / node.js, tente marcado com toc
jonschlinkert

@jonschlinkert Você deve enviá-lo como resposta! Atualmente, as respostas sugerem apenas ferramentas que não são gratuitas ou Python. Não é realmente um ótimo conjunto de opções.
Domi

8
Talvez eu deva mencionar que no LaTeX isso é alcançado com \tableofcontents. Se a roda for reinventada, seria preferível copiar as partes boas.
Eero Aaltonen


Da mesma forma, reStructuredText possui uma diretiva interna para o índice que, da forma mais simples, parece justa .. contents::.
saaj 7/05/19

Respostas:


37

O MultiMarkdown Composer parece gerar um índice para ajudar na edição.

Também pode haver uma ou outra biblioteca que pode gerar TOCs: consulte Extensão do TOC do Python Markdown .


17
MultiMarkdown Composer é MacOS única
chmike

11
Ligação Python Trabalho Markdown TOC: python-markdown.github.io/extensions/toc
John

2
O aplicativo não está disponível na região do Reino Unido.
Kenorb # 03/07

A extensão TOC produz tocs HTML, não Markdown. É notável que isso seja difícil.
Rjurney

395

Você pode tentar.

# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)
4. [Fourth Example](#fourth-examplehttpwwwfourthexamplecom)


## Example
## Example2
## Third Example
## [Fourth Example](http://www.fourthexample.com) 

10
O terceiro exemplo acima não funciona. ## Example ## "Example2" ## Third Example<a name="third-example" /> é a única maneira de fazê-lo engolir espaços até agora. Certamente a 3ª tag seria interpretada como - #Third- seguida por um espaço - e a palavra Exemplo - no seu snippet acima? Hífens não funcionam. Graças
twobob

O exemplo existe para servir como exemplo para mais de uma palavra. Todas as palavras são divididas em maiúsculas e sem espaços.
Rick

6
Funciona bem no RStudio. Só quero acrescentar que os trema alemão eg u necessidade de ser escrita sem trema na âncora ou seja1. [Einführung](#einfuhrung)
steinbock

4
As âncoras não são criadas automaticamente para os cabeçalhos no Bitbucket v4.5.2
Mike Rylander 07/10

11
Esse quarto exemplo é o que eu estava procurando. Obrigado!
Kenecaswell

220

Aqui está um método útil. Deve produzir referências clicáveis ​​em qualquer editor MarkDown.

# Table of contents
1. [Introduction](#introduction)
2. [Some paragraph](#paragraph1)
    1. [Sub paragraph](#subparagraph1)
3. [Another paragraph](#paragraph2)

## This is the introduction <a name="introduction"></a>
Some introduction text, formatted in heading 2 style

## Some paragraph <a name="paragraph1"></a>
The first paragraph text

### Sub paragraph <a name="subparagraph1"></a>
This is a sub paragraph, formatted in heading 3 style

## Another paragraph <a name="paragraph2"></a>
The second paragraph text

Produz:

Índice

  1. Introdução
  2. Algum parágrafo
    1. Subparágrafo
  3. Outro parágrafo

Esta é a introdução

Algum texto de introdução, formatado no estilo do título 2

Algum parágrafo

O texto do primeiro parágrafo

Subparágrafo

Este é um subparágrafo, formatado no estilo de título 3

Outro parágrafo

O texto do segundo parágrafo


22
Eu gosto de colocar a marca âncora na linha acima do cabeçalho; assim, quando o link é clicado, o cabeçalho aparece na página.
mgarey

4
Este foi o único útil para mim. Com títulos longos, é impossível fazê-lo sem tags de âncora.
Matt Fletcher

Isso é muito legal. Comecei a colocar um índice em todos os meus cadernos Jupyter para navegar rapidamente entre as seções.
jackdbd

@mgarey Basta colocar a âncora primeiro: ## <a name="foo" /> Foo
tobias_k

40

Para os usuários do Visual Studio Code , uma boa idéia é usar o plug-in Markdown TOC .

Para instalá-lo, inicie o VS Quick Quick Open ( Control/⌘+ P), cole o seguinte comando e pressione enter.

ext install markdown-toc

E para gerar o sumário, abra a paleta de comandos ( Control/⌘+Shift + P) e selecione Markdown TOC:Insert/Update optionou use Control/⌘+ MT.


7
Nota: Acabei de descobrir que, usando o VSCode de ações, você pode criar links de remarcação para cabeçalhos:, [Section Foo](#foo-header-title)e até funciona fora do modo de visualização (ou seja, na remarcação simples).
Kitsu.eb

4
outra alternativa para VSCode é vscode-markdown que tem vários recursos, TOC incluído
Ciprian Tomoiagă

26

Você pode tentar esse script ruby para gerar o sumário a partir de um arquivo de remarcação.

 #!/usr/bin/env ruby

require 'uri'

fileName = ARGV[0]
fileName = "README.md" if !fileName

File.open(fileName, 'r') do |f|
  inside_code_snippet = false
  f.each_line do |line|
    forbidden_words = ['Table of contents', 'define', 'pragma']
    inside_code_snippet = !inside_code_snippet if line.start_with?('```')
    next if !line.start_with?("#") || forbidden_words.any? { |w| line =~ /#{w}/ } || inside_code_snippet

    title = line.gsub("#", "").strip
    href = URI::encode title.gsub(" ", "-").downcase
    puts "  " * (line.count("#")-1) + "* [#{title}](\##{href})"
  end
end

Ótimo! Apenas uma nota, pode querer adicionar ifndef, includee endif, entre outras directivas de pré-processamento, para a lista de palavras proibidas. Além disso, definir a lista fora do escopo do loop evita a necessidade de restabelecê-la a cada iteração. Além disso, isso selecionará comentários de qualquer idioma que use #sintaxe de comentários, incluindo Ruby, o que não é bom. Estou disposto a editar, se desejar. No entanto, este é um ótimo começo e funcionou bem para meus propósitos. Muito obrigado!
22616 Jeff

Isso funciona apenas com títulos atx (ou seja, aqueles que começam com #), não com os de setext (sublinhados).
gozzilli

obrigado por isso, se você estiver usando isso para redcarpet on trilhos, você deve ir com title.parameterizeo href, obrigado!
Alexis11

25

Existem 2 maneiras de criar seu sumário (sumário) no seu documento de remarcação.

1. Manualmente

# My Table of content
- [Section 1](#id-section1)
- [Section 2](#id-section2)

<div id='id-section1'/>
## Section 1
<div id='id-section2'/>
## Section 2

2. Programaticamente

Você pode usar, por exemplo, um script que geram resumo para você, dê uma olhada ao meu projeto no github - summarizeMD -

Eu tentei também outro módulo script / npm (por exemplo, doctoc ), mas ninguém reproduz um sumário com âncoras de trabalho.


`` <div id = ... `não é reconhecido pelo MarkdownPad2 (Windows)
chmike

Funciona apenas na mesma pasta, também não funciona para títulos de texto fixo.
gozzilli

25
# Table of Contents
1. [Example](#example)
2. [Example2](#example2)
3. [Third Example](#third-example)

## Example [](#){name=example}
## Example2 [](#){name=example2}
## [Third Example](#){name=third-example}

Se você usar a remarcação extra, não esqueça que pode adicionar atributos especiais a links, cabeçalhos, cercas de código e imagens.
https://michelf.ca/projects/php-markdown/extra/#spe-attr


11

Tags âncora geradas por diferentes analisadores Markdown não são iguais.

Se você estiver trabalhando com analisadores Markdown GFM (GitHub Flavored Markdown) ou Redcarpet, escrevi um plug-in Vim para lidar com o índice.

Recursos

  1. Gere um índice para arquivos Markdown.

    Analisadores Markdown suportados:

    • GFM (remarcação com sabor do GitHub)
    • Tapete vermelho
  2. Atualize o índice existente.

  3. Atualizar automaticamente o índice existente ao salvar.

Screenshots

vim-markdown-toc

Uso

Gerar sumário

Mova o cursor para a linha que você deseja anexar ao sumário e digite um comando abaixo. O comando irá gerar títulos após o cursor no sumário.

  1. :GenTocGFM

    Gere o índice no estilo de link GFM.

    Este comando é adequado para arquivos Markdown em repositórios do GitHub, como README.md, e arquivos Markdown para o GitBook.

  2. :GenTocRedcarpet

    Gere o índice no estilo de link Redcarpet.

    Este comando é adequado para Jekyll ou em qualquer outro lugar usar Redcarpet como seu analisador Markdown.

    Você pode ver aqui as diferenças entre os links GFM e Redcarpet style toc.

Atualizar o índice existente manualmente

Geralmente, você não precisa fazer isso, o índice existente será atualizado automaticamente ao salvar por padrão. Se você quiser fazê-lo manualmente, basta usar:UpdateToc comando

Downloads e documentos

https://github.com/mzlogin/vim-markdown-toc


10

Você também pode usar pandoco "canivete suíço" para converter "um formato de marcação em outro" . Ele pode gerar automaticamente uma tabela de conteúdo no documento de saída se você fornecer o--toc argumento.

Dica: se você deseja obter um sumário html, também é necessário fornecer-s que gera um documento independente.

Exemplo de linha de comando do shell:

./pandoc -s --toc input.md -o output.html



7

Você pode gerá-lo usando este one-liner do bash. Assume que seu arquivo de marcação é chamado FILE.md.

echo "## Contents" ; echo ; 
cat FILE.md | grep '^## ' | grep -v Contents | sed 's/^## //' | 
  while read -r title ; do 
    link=$(echo $title | tr 'A-Z ' 'a-z-') ; 
    echo "- [$title](#$link)" ; 
    done

Isso é ótimo. Vale a pena reescrevê-lo como um script adequado, com o nome do arquivo como argumento, e talvez com o manuseio das subseções.
MasterScrat

6

Eu apenas codifiquei uma extensão para python-markdown , que usa seu analisador para recuperar cabeçalhos e gera um TOC como lista não ordenada no formato Markdown com links locais. O arquivo é

... e deve ser colocado no markdown/extensions/diretório na instalação de remarcação. Então, tudo que você precisa fazer é digitar <a>tags âncora com um id="..."atributo como referência - portanto, para um texto de entrada como este:

$ cat test.md 
Hello
=====

## <a id="sect one"></a>SECTION ONE ##

something here

### <a id='sect two'>eh</a>SECTION TWO ###

something else

#### SECTION THREE

nothing here

### <a id="four"></a>SECTION FOUR

also...

... a extensão pode ser chamada assim:

$ python -m markdown -x md_toc test.md 
* Hello
    * [SECTION ONE](#sect one)
        * [SECTION TWO](#sect two)
            * SECTION THREE
        * [SECTION FOUR](#four)

... e, em seguida, você pode colar novamente esse toc no seu documento de remarcação (ou ter um atalho no seu editor de texto, que chama o script no documento aberto no momento e depois insere o sumário resultante no mesmo documento).

Observe que versões mais antigas de python-markdownnão possuem um __main__.pymódulo e, como tal, a chamada de linha de comando conforme acima não funcionará para essas versões.


6

Como mencionado em outras respostas, existem várias maneiras de gerar um sumário automaticamente. A maioria é de software livre e pode ser adaptada às suas necessidades.

O que estava faltando, no entanto, é uma formatação visualmente atraente para um índice, usando as opções limitadas fornecidas pelo Markdown. Criamos o seguinte:

Código

## Content

**[1. Markdown](#heading--1)**

  * [1.1. Markdown formatting cheatsheet](#heading--1-1)
  * [1.2. Markdown formatting details](#heading--1-2)

**[2. BBCode formatting](#heading--2)**

  * [2.1. Basic text formatting](#heading--2-1)

      * [2.1.1. Not so basic text formatting](#heading--2-1-1)

  * [2.2. Lists, Images, Code](#heading--2-2)
  * [2.3. Special features](#heading--2-3)

----

Dentro do documento, você colocaria os marcadores de subparte de destino como este:

<div id="heading--1-1"/>
### 1.1. Markdown formatting cheatsheet

Dependendo de onde e como você usa o Markdown, o seguinte também deve funcionar e fornece um código de aparência mais agradável:

### 1.1. Markdown formatting cheatsheet <a name="heading--1-1"/>

Exemplo de renderização

Conteúdo

1. Remarcação

2. Formatação BBCode


Vantagens

  • Você pode adicionar quantos níveis de capítulos e sub-capítulos forem necessários. No Sumário, elas apareceriam como listas não ordenadas aninhadas em níveis mais profundos.

  • Não há uso de listas ordenadas. Isso criaria um recuo, não vincularia o número e não pode ser usado para criar numeração de classificação decimal como "1.1".

  • Não há uso de listas para o primeiro nível. Aqui, o uso de uma lista não ordenada é possível, mas não é necessário: o recuo e o marcador apenas adicionam desordem visual e nenhuma função aqui; portanto, não usamos uma lista para o primeiro nível de sumário.

  • Ênfase visual nas seções de primeiro nível na tabela de conteúdo em negrito.

  • Marcadores de subparte curtos e significativos que parecem "bonitos" na barra de URL do navegador, em #heading--1-1vez de marcadores que contêm partes transformadas do cabeçalho real.

  • O código usa os títulos H2 ( ## …) para as seções, os títulos H3 ( ### …) para os subtítulos etc. Isso facilita a leitura do código-fonte, pois ## …fornece uma pista visual mais forte ao rolar em comparação com o caso em que as seções começariam com os títulos H1 ( # …) Ainda é logicamente consistente quando você usa o cabeçalho H1 para o próprio título do documento.

  • Por fim, adicionamos uma boa regra horizontal para separar o índice do conteúdo real.

Para saber mais sobre essa técnica e como a usamos dentro do Discourse , consulte aqui .


5

Eu escrevi um script python que analisa um arquivo de remarcação e gera um índice como uma lista de remarcação: md-to-toc

Ao contrário de outros scripts que encontrei, o md-to-toc suporta corretamente títulos duplicados. Também não requer uma conexão com a Internet, portanto funciona em qualquer arquivo md, não apenas nos disponíveis em um repositório público.


5

No Visual Studio Code (VSCode), você pode usar a extensão Markdown All in One .

Depois de instalado, siga as etapas abaixo:

  1. Pressione CTRL+ SHIFT+P
  2. Selecione remarcação: criar sumário




4

Basta usar o seu editor de texto com um plugin.

Seu editor possivelmente possui um pacote / plugin para lidar com isso para você. Por exemplo, no Emacs , você pode instalar o gerador de markdown-toc TOC. Então, enquanto você edita, basta ligar repetidamenteM-x markdown-toc-generate-or-refresh-toc . Isso vale uma ligação importante se você quiser fazer isso com frequência. É bom gerar um sumário simples sem poluir seu documento com âncoras HTML.

Outros editores têm plugins semelhantes, portanto, a lista popular é algo como:


2

Com base em albertodebortoli, a resposta criou a função com verificações adicionais e substituição de sinais de pontuação.

# @fn       def generate_table_of_contents markdown # {{{
# @brief    Generates table of contents for given markdown text
#
# @param    [String]  markdown Markdown string e.g. File.read('README.md')
#
# @return   [String]  Table of content in markdown format.
#
def generate_table_of_contents markdown
  table_of_contents = ""
  i_section = 0
  # to track markdown code sections, because e.g. ruby comments also start with #
  inside_code_section = false
  markdown.each_line do |line|
    inside_code_section = !inside_code_section if line.start_with?('```')

    forbidden_words = ['Table of contents', 'define', 'pragma']
    next if !line.start_with?('#') || inside_code_section || forbidden_words.any? { |w| line =~ /#{w}/ }

    title = line.gsub("#", "").strip
    href = title.gsub(/(^[!.?:\(\)]+|[!.?:\(\)]+$)/, '').gsub(/[!.,?:; \(\)-]+/, "-").downcase

    bullet = line.count("#") > 1 ? " *" : "#{i_section += 1}."
    table_of_contents << "  " * (line.count("#") - 1) + "#{bullet} [#{title}](\##{href})\n"
  end
  table_of_contents
end


2

Para mim, a solução proposta pelo @Tum funciona como um encanto para um sumário com 2 níveis. No entanto, para o terceiro nível, não funcionou. Não exibiu o link como nos dois primeiros níveis; em vez disso, exibe o texto sem formatação 3.5.1. [bla bla bla](#blablabla) <br>.

Minha solução é uma adição à solução do @Tum (que é muito simples) para pessoas que precisam de um índice com 3 níveis ou mais.

No segundo nível, uma guia simples fará o recuo corretamente para você. Mas ele não suporta 2 guias. Em vez disso, você deve usar uma guia e adicionar quantas&nbsp; necessário para alinhar o terceiro nível corretamente.

Aqui está um exemplo usando 4 níveis (mais altos, por mais horrível que seja):

# Table of Contents
1. [Title](#title) <br>
    1.1. [sub-title](#sub_title) <br>
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1. [sub-sub-title](#sub_sub_title)
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;1.1.1.1. [sub-sub-sub-title](#sub_sub_sub_title)

# Title <a name="title"></a>
Heading 1

## Sub-Title <a name="sub_title"></a>
Heading 2

### Sub-Sub-Title <a name="sub_sub_title"></a>
Heading 3

#### Sub-Sub-Sub-Title <a name="sub_sub_sub_title"></a>
Heading 4

Isso fornece o seguinte resultado, onde cada elemento do sumário é um link para sua seção correspondente. Observe também o<br> fim de adicionar uma nova linha em vez de estar na mesma linha.

Índice

  1. Título
    1.1 Subtítulo
           1.1.1. -Sub-sub Título
                     1.1.1.1. Sub-Sub-Sub-Título

Título

Cabeçallho 1

Subtítulo

Rubrica 2

Subtítulo

Rubrica 3

Sub-Sub-Sub-Título

Rubrica 4


1

Dependendo do seu fluxo de trabalho, você pode querer observar a redução

Essa é uma bifurcação da original ( http://strapdownjs.com ) que adiciona a geração da tabela de conteúdo.

Há um arquivo de configuração do apache no repositório (talvez ainda não esteja atualizado corretamente) para encerrar a remarcação em tempo real, se você preferir não escrever em arquivos html.


1

Não tenho certeza, qual é a documentação oficial para remarcação. A referência cruzada pode ser escrita apenas entre colchetes [Heading]ou com colchetes vazios [Heading][].

Ambos os trabalhos usam pandoc . Então, eu criei um script bash rápido, que substituirá $ TOC no arquivo md pelo seu TOC. (Você precisará do envsubst, isso pode não fazer parte da sua distribuição)

#!/bin/bash
filename=$1
__TOC__=$(grep "^##" $filename | sed -e 's/ /1. /;s/^##//;s/#/   /g;s/\. \(.*\)$/. [\1][]/')
export __TOC__
envsubst '$__TOC__' < $filename

1

Se você usar o Eclipse, poderá usar o atalho Ctrl+ O(estrutura de tópicos), isso mostrará o equivalente ao índice e permitirá pesquisar nos títulos das seções (preenchimento automático).

Você também pode abrir a exibição Estrutura de tópicos (Janela -> Mostrar exibição -> Estrutura de tópicos), mas ela não possui pesquisa de preenchimento automático.


1

Use toc.py, que é um pequeno script python que gera um índice para sua remarcação.

Uso:

  • No seu arquivo Markdown, adicione <toc>onde deseja que o índice seja colocado.
  • $python toc.py README.md(Use seu nome de arquivo de remarcação em vez de README.md )

Felicidades!


Seu script é legal, mas não cria uma âncora antes de cada título. Necessário pelo menos em bitbucket.
Paul Rougieux

1

Usei https://github.com/ekalinin/github-markdown-toc, que fornece um utilitário de linha de comando que gera automaticamente o índice a partir de um documento de redução.

Não há plugins, macros ou outras dependências. Após instalar o utilitário, basta colar a saída do utilitário no local no documento em que você deseja o seu índice. Muito simples de usar.

$ cat README.md | ./gh-md-toc -


1

Existe um script Ruby chamado mdtoc.rb que pode gerar automaticamente um Índice GFM Markdown e é semelhante, mas um pouco diferente de outros scripts publicados aqui.

Dado um arquivo Markdown de entrada como:

# Lorem Ipsum

Lorem ipsum dolor sit amet, mei alienum adipiscing te, has no possit delicata. Te nominavi suavitate sed, quis alia cum no, has an malis dictas explicari. At mel nonumes eloquentiam, eos ea dicat nullam. Sed eirmod gubergren scripserit ne, mei timeam nonumes te. Qui ut tale sonet consul, vix integre oportere an. Duis ullum at ius.

## Et cum

Et cum affert dolorem habemus. Sale malis at mel. Te pri copiosae hendrerit. Cu nec agam iracundia necessitatibus, tibique corpora adipisci qui cu. Et vix causae consetetur deterruisset, ius ea inermis quaerendum.

### His ut

His ut feugait consectetuer, id mollis nominati has, in usu insolens tractatos. Nemore viderer torquatos qui ei, corpora adipiscing ex nec. Debet vivendum ne nec, ipsum zril choro ex sed. Doming probatus euripidis vim cu, habeo apeirian et nec. Ludus pertinacia an pro, in accusam menandri reformidans nam, sed in tantas semper impedit.

### Doctus voluptua

Doctus voluptua his eu, cu ius mazim invidunt incorrupte. Ad maiorum sensibus mea. Eius posse sonet no vim, te paulo postulant salutatus ius, augue persequeris eum cu. Pro omnesque salutandi evertitur ea, an mea fugit gloriatur. Pro ne menandri intellegam, in vis clita recusabo sensibus. Usu atqui scaevola an.

## Id scripta

Id scripta alterum pri, nam audiam labitur reprehendunt at. No alia putent est. Eos diam bonorum oportere ad. Sit ad admodum constituto, vide democritum id eum. Ex singulis laboramus vis, ius no minim libris deleniti, euismod sadipscing vix id.

Ele gera este índice:

$ mdtoc.rb FILE.md 
#### Table of contents

1. [Et cum](#et-cum)
    * [His ut](#his-ut)
    * [Doctus voluptua](#doctus-voluptua)
2. [Id scripta](#id-scripta)

Veja também meu post sobre este tópico.

Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.