Existe um utilitário de linha de comando para renderizar o Markdown com sabor do GitHub?

414

Gostaria de saber se existe um utilitário de linha de comando para pegar um arquivo Markdown com sabor do GitHub e renderizá-lo em HTML.

Estou usando um wiki do GitHub para criar conteúdo do site. Eu clonei o repositório no meu servidor e gostaria de processá-lo em HTML comum. É importante para mim que o que aparece no GitHub seja exatamente como ele deve aparecer no meu site. Eu também gostaria muito de usar os blocos cercados ~~~, então prefiro não usar apenas a sintaxe padrão do Markdown.

Eu olhei um pouco para a visualização ao vivo do JavaScript pensando que poderia conectá-lo ao Node.js, mas eles dizem que está obsoleto. Eu olhei para o repositório redcarpet, mas ele não parece ter uma interface de linha de comando.

Eu rolei minha própria solução, no entanto, como nenhuma solução aqui é claramente melhor que as outras, deixarei a pergunta sem uma resposta selecionada.

McLeopold
fonte
2
RE: UPDATE: Se eu adicionasse um --outargumento para manipular para renderizar em um arquivo HTML em vez do navegador, isso seria aceitável?
3130 Joe
@ Joe, por favor adicione essa opção!
bguiz
O @McLeopold @bguiz acabou de implantar a --exportopção, que renderiza o GFM e seus estilos em um único arquivo. Isso responde a pergunta?
31413 Joe
3
@ McLeopold, Joe meio que tirou isso do papel ao criar uma solução reutilizável simples, que pode dar a resposta.
James McMahon
1
O próprio Github usa o Sundown . Veja stackoverflow.com/a/7694931/632951
Pacerier

Respostas:

447

Escrevi uma pequena CLI em Python e adicionei suporte a GFM. Chama-se Grip (Visualização instantânea do Github Readme) .

Instale-o com:

$ pip install grip

E para usá-lo, basta:

$ grip

Em seguida, visite localhost:5000para visualizar o readme.mdarquivo nesse local.

Você também pode especificar seu próprio arquivo:

$ grip CHANGES.md

E mude a porta:

$ grip 8080

E, é claro, processe especificamente o GitHub-Flavored Markdown, opcionalmente com o contexto do repositório:

$ grip --gfm --context=username/repo issue.md

Recursos notáveis:

  • Renderiza as páginas para aparecer exatamente como no GitHub
  • Blocos cercados
  • API Python
  • Navegue entre os arquivos vinculados (obrigado, vladwing !) Adicionados na versão 2.0
  • Exportar para um único arquivo (obrigado, iliggio !) Adicionado na versão 2.0
  • Novo: Leia stdine exporte para stdout adicionado ao 3.0

Espero que isso ajude alguém aqui. Confira .

Joe
fonte
1
Funciona muito bem e você não pode superar a facilidade de instalação dos Pythonistas!
RichVel
29
Esse deve ser o primeiro hit da "visualização de remarcação do github". Tudo o resto é complicado, não funciona ou não possui todos os recursos do GitHub. gripfunciona imediatamente.
Blu
1
@Houdini Essa questão está desatualizada. O Flask suporta 3.3, consulte flask.pocoo.org/docs/python3 . Aqui está um tópico mais recente do Github sobre o tópico github.com/mitsuhiko/flask/issues/587 . Se houver outra dependência que precise ser atualizada, sinta-se à vontade para abrir um problema ou uma solicitação de recebimento.
31813 Joe
3
Note-se que este pacote requer uma conexão ativa com a Internet e suas credenciais de autenticação do github (fornecidas na linha de comando) se você fizer mais de 60 atualizações por hora.
leo
13
Como mencionado anteriormente, não acho que essa seja uma solução particularmente boa, porque tudo o que faz vai para o Github e faz com que o Github renderize seu Markdown. Ele requer uma conexão de Internet funcionando com acesso ao Github e, se o Github morrer, essa ferramenta para de funcionar. Prefiro ter uma solução completamente offline.
Jez
114

Não encontrei um método rápido e fácil para o Markdown com sabor do GitHub, mas encontrei uma versão um pouco mais genérica - Pandoc . Ele converte de / para vários formatos, incluindo Markdown, Rest, HTML e outros.

Também desenvolvi um Makefilepara converter todos os arquivos .md para .html (em grande parte para o exemplo de Redação, Markdown e Pandoc ):

# 'Makefile'
MARKDOWN = pandoc --from gfm --to html --standalone
all: $(patsubst %.md,%.html,$(wildcard *.md)) Makefile

clean:
    rm -f $(patsubst %.md,%.html,$(wildcard *.md))
    rm -f *.bak *~

%.html: %.md
    $(MARKDOWN) $< --output $@
Alister Bulman
fonte
4
Eu tenho usado "watch pandoc ..." para converter continuamente um arquivo de remarcação para html, e a extensão "live reload" do Chrome para obter em tempo real a funcionalidade "ficar onde estou rolada também" com isso, e funciona muito bem . chrome.google.com/webstore/detail/livereload/…
Brad Parks
1
Pandoc lê bem o GFM, mas não gera o mesmo HTML que o GitHub - por exemplo, se você tiver uma <pre/>tag de várias linhas na sua fonte GFM, o Pandoc colocará <br/>tags nas quebras de linha, enquanto o renderizador do GitHub, no entanto tira o espaço em branco à esquerda, parece deixar o conteúdo em paz.
David Moles
1
Como obter um estilo agradável no HTML resultante? Minha saída ainda é renderizada com Times New Roman, por exemplo.
Desenvolvedor Holístico
As instruções de instalação do Pandoc estão aqui . No macOS:brew install pandoc
Master of Ducks
1
nem os formatos gfmnem os de markdown_githubentrada processam corretamente coisas como blocos de código.
user5359531
29

Talvez isso possa ajudar:

gem install github-markdown

Não existe documentação, mas obtive-a na documentação do gollum . Olhando para rubydoc.info , parece que você pode usar:

require 'github/markdown'  
puts GitHub::Markdown.render_gfm('your markdown string')

no seu código Ruby. Você pode agrupar isso facilmente em um script para transformá-lo em um utilitário de linha de comando:

#!/usr/bin/env ruby

# render.rb
require 'github/markdown'

puts GitHub::Markdown.render_gfm File.read(ARGV[0])

Execute-o com ./render.rb path/to/my/markdown/file.md. Observe que isso não é seguro para uso em produção sem higienização.

James Lim
fonte
1
Graças Jim, devido aos exemplos praticamente inexistentes, eu estava preso no exigem passo (substituindo traço com Slash fez) ..;)
plesatejvlk
Isso é ótimo se você já estiver usando o NPM. Eu tive que usá-lo, por causa do DOxygen, causando-me problemas constantes com a remarcação específica para o github + exportando para HTML.
precisa saber é o seguinte
isso está sendo executado localmente ou está enviando dados para a API do GitHub?
user5359531
28
pip3 install --user markdown
python3 -m markdown readme.md > readme.html

Ele não lida com extensões do GitHub, mas é melhor que nada. Eu acredito que você pode estender o módulo para lidar com as adições ao GitHub.

Gringo Suave
fonte
1
/ usr / bin / python: remarcação é um pacote e não pode ser executado diretamente
Kazimieras Aliulis
2
Saída HTML simples, sem tags sofisticadas.
Halil Kaskavalci
23

Provavelmente não é o que você deseja, mas desde que você mencionou o Node.js.: não encontrei uma boa ferramenta para visualizar a documentação do GitHub Flavored Markdown na unidade local antes de enviá-los para o GitHub, então hoje eu criei um, com base no Node.js.: https : //github.com/ypocat/gfms

Portanto, talvez você possa reutilizar o showdown.js para o seu Wiki, se sua pergunta ainda for real. Caso contrário, talvez outras pessoas que enfrentam o mesmo problema que eu encontrem (exatamente como eu) essa pergunta e essa resposta.

youurayy
fonte
Muito bem, cara. Evita que eu precise recorrer a Ruby ou Python quando estou escrevendo um aplicativo de nó, o que é ótimo.
jedd.ahyoung
19

Para ler um arquivo README.md no terminal, eu uso:

pandoc README.md | lynx -stdin

O Pandoc gera no formato HTML, que o Lynx processa no seu terminal.

Funciona muito bem: preenche meu terminal, os atalhos são mostrados abaixo, eu posso rolar e os links funcionam! Porém, existe apenas um tamanho de fonte, mas as cores + indentação + alinhamento compensam isso.

Instalação:

sudo apt-get install pandoc lynx
Barry Staes
fonte
1
A pergunta é especificamente sobre o uso da linha de comando. Antes de escrever seu próprio script ruby ​​(ou servidor de nó egad), experimente.
Cora Middleton
Exatamente isso funciona dentro do seu terminal. Ou se o seu navegador favorito (da área de trabalho?) Puder acessar essa pasta pandoc readme.md -o readme.md.htmle abrir o arquivo resultante.
Barry Staes
@ baerry-staes Sim, desculpe, espero que fique claro que a sua foi a minha resposta preferida.
Cora Middleton
@ JustinMiddleton sim, entendi, obrigado. Meu comentário foi apenas para adicionar algumas informações extras para os usuários de desktop. Imaginei que alguém um dia lendo isso poderia ser útil.
Barry Staes
1
Eu tentei cerca de 5-6 outros leitores de console md e essa tem sido de longe a melhor solução. Acabei de adicionar a função mais básica à minha configuração para torná-la um pouco mais rápida de usar. function md { pandoc $@ | lynx -stdin }
Russ Brown
17

O GitHub tem uma API Markdown que você pode usar.

kehers
fonte
5
jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < README.md | curl --data @- https://api.github.com/markdown > README.html
Vebjorn Ljosa
@VebjornLjosa * that * or grip... Você escolheu. : P
aaaa 27/11
13

Use marcado . Ele suporta o GitHub Flavored Markdown, pode ser usado como um módulo Node.js. e na linha de comando.

Um exemplo seria:

$ marked -o hello.html
hello world
^D
$ cat hello.html
<p>hello world</p>
zemirco
fonte
1
Percebi que isso não suporta recursos como destaque de sintaxe para blocos de código e recursos mais recentes, como listas de verificação. Mas ei, fica na maior parte do caminho!
bguiz
Muito bom, a única coisa que me falta é algumas bordas para as mesas. Bem, pelo menos eu posso renderizá-los, isso é exatamente o que eu preciso. Tubo no GFM, cachimbo HTML :)
Xandaros
Estou confuso sobre este exemplo, o que é ^D?
Mateus
10

Isso é principalmente uma resposta à resposta de @ barry-staes para usar o Pandoc . O Homebrew também o tem, se você estiver em um Mac:

brew install pandoc

Pandoc suporta GFM como um formato de entrada através do markdown_githubnome.

Saída para arquivo

cat foo.md | pandoc -f markdown_github > foo.html

Abrir no Lynx

cat foo.md | pandoc -f markdown_github | lynx -stdin # To open in Lynx

Abra no navegador padrão no OS X

cat foo.md | pandoc -f markdown_github > foo.html && open foo.html # To open in the default browser on OS X`

Integração TextMate

Você sempre pode canalizar a seleção atual ou o documento atual para uma das opções acima, como a maioria dos editores permite. Você também pode configurar facilmente o ambiente para pandocsubstituir o processador Markdown padrão usado pelo pacote Markdown .

Primeiro, crie um script de shell com o seguinte conteúdo (eu vou chamá-lo ghmarkdown):

#!/bin/bash
# Note included, optional --email-obfuscation arg
pandoc -f markdown_github --email-obfuscation=references

Você pode definir a TM_MARKDOWNvariável (em Preferências → Variáveis) como /path/to/ghmarkdowne ela substituirá o processador Markdown padrão.

Cora Middleton
fonte
10

Criei uma ferramenta semelhante à funcionalidade de visualização prévia do Atom, mas como um aplicativo independente. Não tenho certeza se é isso que você está procurando, mas pode ser útil. - https://github.com/yoshuawuyts/vmd

vmd

Yoshua Wuyts
fonte
Vocês ainda estão apoiando isso? Eu tentei instalar com o NPM hoje, mas não há dados. > download do electron-v0.36.9-win32-x64.zip> Erro: certificado
autoassinado
1
Sim, nós somos! Em qual versão do npm / node você executou isso? - sinta-se à vontade para abrir um problema no GH e daremos uma olhada nisso. Obrigado!
Yoshua Wuyts
8

pandoccom browserfunciona bem para mim.

Uso: cat README.md | pandoc -f markdown_github | browser

Instalação (supondo que você esteja usando o Mac OSX):

  • $ brew install pandoc

  • $ brew install browser

Ou no Debian / Ubuntu: apt-get install pandoc browser

pedreiro
fonte
1
apt-get isntall pandocvai fazer, não há necessidade de usar coisas locais inseguras, como cerveja.
Dominik George
1
@DominikGeorge há um erro de digitação, é instalar , não isntall
Federico Tomassetti
11
@DominikGeorge não há apt-get no macOS.
richrad
6

Consulte também https://softwareengineering.stackexchange.com/a/128721/24257 .


Se você estiver interessado em como nós [Github] processamos arquivos Markdown, você pode conferir o Redcarpet , nossa interface Ruby para a biblioteca do Sundown.

O script Ruby, que usa Redcarpet , será "utilitário de linha de comando", se você tiver Ruby local

Lazy Badger
fonte
Não têm idéias - Eu não escrevo Ruby e eu não li fontes RedCarpet
preguiçoso Badger
@ LazyBadger, Sundown é o analisador real (escrito em C). Redcarpet não é necessário.
Pacerier
6

Com base neste comentário , escrevi uma linha para acessar a API do Github Markdown usando curle jq.

Cole esta função bash na linha de comando ou no seu ~/.bash_profile:

mdsee(){ 
    HTMLFILE="$(mktemp -u).html"
    cat "$1" | \
      jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' | \
      curl -s --data @- https://api.github.com/markdown > "$HTMLFILE"
    echo $HTMLFILE
    open "$HTMLFILE"
}

E então, para ver o HTML renderizado no navegador executado:

mdsee readme.md

Substitua open "$HTMLFILE"por lynx "$HTMLFILE"se precisar de uma solução terminal pura.

notpeter
fonte
4

O GitHub (desde) desenvolveu um bom editor de texto modular chamado Atom (baseado no Chromium e usa módulos Node.js. para pacotes).

Um pacote pré-instalado padrão O Markdown Preview permite exibir sua visualização em uma guia separada usando Ctrl+ Shift+ M.

Eu não testei sua sintaxe completa, mas como é proveniente do GitHub, ficaria muito surpreso se a sintaxe da visualização fosse diferente da deles (blocos protegidos usando ~~~trabalho).

Agora, embora não seja tecnicamente baseado em linha de comando, ele usa o Node.js e gera um renderizador baseado em DOM , o que pode ajudar qualquer um que tente renderizar HTML baseado em sintaxe do GitHub em um servidor da Web baseado em Node.js. / README.md offline.

That
fonte
1
No Atom, você pode instalar um pacote chamado gfm-pdf ( atom.io/packages/gfm-pdf ), que exporta seu documento de remarcação para um documento HTML e / ou PDF. A biblioteca wkhtmltopdf é necessária.
spren9er 11/09/2015
3

Existe uma ferramenta realmente agradável e simples para navegar nos documentos GFM Markdown:

GFMS - Servidor de Markdown com sabor do Github

É um servidor HTTP simples e leve (sem necessidade de configuração). Você pode iniciar em qualquer diretório que contenha arquivos de descontos para procurá-los.

Recursos:

  • Suporte completo para Markdown GFM
  • Destaque da sintaxe do código fonte
  • Procurando arquivos e diretórios
  • Saída agradável (e folhas de estilo CSS configuráveis)
  • Exportar para PDF
Pawel Wiejacha
fonte
3

Eu consegui usar um script Ruby de uma linha para esse fim (embora tivesse que ir em um arquivo separado). Primeiro, execute estes comandos uma vez em cada máquina cliente onde você enviará documentos a partir de:

gem install github-markup
gem install commonmarker

Em seguida, instale este script na sua imagem do cliente e chame-o render-readme-for-javadoc.rb:

require 'github/markup'

puts GitHub::Markup.render_s(GitHub::Markups::MARKUP_MARKDOWN, File.read('README.md'))

Por fim, invoque-o assim:

ruby ./render-readme-for-javadoc.rb >> project/src/main/javadoc/overview.html

ETA: Isso não o ajudará com o Markdown StackOverflow, que parece estar falhando nesta resposta.

Pr0methean
fonte
Eu acho que essa é a resposta "mais próxima da fonte" de todas elas, pois essas ferramentas são as usadas pelo github.
Memeelyk
3

Eu uso o Pandoc com a opção --from=gfmpara o GitHub Flavored Markdown assim:

$ pandoc my_file.md   --from=gfm -t html -o my_file.html
Asme Just
fonte
Com pandoc 1.16.0.2 no Linux Mint 18 eu recebo um erro: pandoc: Unknown reader: gfm. Indo para 2.2.1 corrige isso.
kidmose
Eu testei com o Pandoc 2.1.2.
Asme Apenas
como instalar o 2.2.1 no ubuntu?
Alexander Mills
@AlexanderMills Você tentou sudo apt install pandoc?
Asme Apenas
2

Melhorando a solução da @ barry-stae. Coloque este trecho em ~ / .bashrc

function mdviewer(){
  pandoc $* | lynx -stdin
}

Em seguida, podemos visualizar rapidamente o arquivo na linha de comando. Também funciona bem em sessões SSH / Telnet.

mdviewer README.md
Sandeep
fonte
2

Adição tardia, mas showdownjs possui uma ferramenta CLI que você pode usar para analisar MD para HTML.

Tivie
fonte
1

Encontrei um site que fará isso por você: http://tmpvar.com/markdown.html . Cole no seu Markdown e ele será exibido para você. Parece funcionar muito bem!

No entanto, ele não parece lidar com a opção de destaque de sintaxe do código; isto é, o ~~~rubyrecurso não funciona. Apenas imprime 'rubi'.

JESii
fonte
não tmpvar não parece fazer melhorias versão GFM como mesas
Greg
0

Para melhorar as respostas @ barry-stae e @Sandeep para usuários regulares de elinks, você adicionaria o seguinte ao .bashrc:

function mdviewer() {
  pandoc $* | elinks --force-html
}

Não se esqueça de instalar o pandoc (e elinks).

daBertl
fonte
0

Com base na resposta de Jim Lim , instalei a gema GitHub Markdown. Isso incluía um script chamado gfm que pega um nome de arquivo na linha de comando e grava o HTML equivalente na saída padrão. Modifiquei isso um pouco para salvar o arquivo em disco e abrir o navegador padrão com o launchy:

#!/usr/bin/env ruby

HELP = <<-help
  Usage: gfm [--readme | --plaintext] [<file>]
  Convert a GitHub-Flavored Markdown file to HTML and write to standard output.
  With no <file> or when <file> is '-', read Markdown source text from standard input.
  With `--readme`, the files are parsed like README.md files in GitHub.com. By default,
  the files are parsed with all the GFM extensions.
help

if ARGV.include?('--help')
  puts HELP
  exit 0
end

root = File.expand_path('../../', __FILE__)
$:.unshift File.expand_path('lib', root)

require 'github/markdown'
require 'tempfile'
require 'launchy'

mode = :gfm
mode = :markdown if ARGV.delete('--readme')
mode = :plaintext if ARGV.delete('--plaintext')

outputFilePath = File.join(Dir.tmpdir, File.basename(ARGF.path))  + ".html"

File.open(outputFilePath, "w") do |outputFile |
    outputFile.write(GitHub::Markdown.to_html(ARGF.read, mode))
end

outputFileUri = 'file:///' + outputFilePath

Launchy.open(outputFileUri)
gerrard00
fonte
1
Eu tentei isso com blocos cercados para Ruby e Pepino. Embora as cercas ( ruby, pepino etc.) pareçam ser reconhecidas como cercas (porque são renderizadas em texto de largura fixa), não há realce de sintaxe. Alguma idéia do porquê?
Keith Bennett
0

Uma abordagem 'rápida e suja' é fazer o download das páginas HTML do wiki usando o wgetutilitário, em vez de cloná-lo. Por exemplo, foi assim que baixei o wiki do Hystrix no GitHub (estou usando o Ubuntu Linux):

 $ wget -e robots=off -nH -E -H -k -K -p https://github.com/Netflix/Hystrix/wiki
 $ wget -e robots=off -nH -E -H -k -K -I "Netflix/Hystrix/wiki" -r -l 1 https://github.com/Netflix/Hystrix/wiki

A primeira chamada fará o download da página de entrada do wiki e de todas as suas dependências. O segundo chamará todas as subpáginas nele. Você pode navegar agora pelo wiki abrindo Netflix/Hystrix/wiki.1.html.

Observe que as duas chamadas para wgetsão necessárias. Se você acabou de executar o segundo, perderá algumas dependências necessárias para mostrar as páginas corretamente.

Luis Rodero-Merino
fonte
-1

Recentemente fiz o que você quer, porque precisava gerar documentação a partir de arquivos Markdown e o estilo GitHub é muito bom. Tente. Está escrito em Node.js.

gfm

Gabriel Llamas
fonte
Eu sei, o módulo não foi atualizado em 9 meses, por que você rebate uma postagem antiga?
Gabriel Llamas