¿Hay una utilidad de línea de comandos para renderizar GitHub con sabor a Markdown?


414

Me pregunto si hay una utilidad de línea de comandos para tomar un archivo Markdown con sabor a GitHub y renderizarlo en HTML.

Estoy usando un wiki de GitHub para crear contenido del sitio web. He clonado el repositorio en mi servidor y luego me gustaría procesarlo en HTML normal. Es importante para mí que lo que aparece en GitHub es exactamente cómo debería verse para mi sitio web. También me gustaría usar los bloques cercados ~~~, así que prefiero no usar solo la sintaxis estándar de Markdown.

He examinado un poco la vista previa en vivo de JavaScript pensando que podría conectarla a Node.js, pero dicen que está en desuso. He mirado el repositorio de redcarpet, pero no parece que tenga una interfaz de línea de comandos.

Sin embargo, desarrollé mi propia solución, dado que ninguna solución aquí es claramente mejor que las demás, dejaré la pregunta sin una respuesta seleccionada.


2
RE: ACTUALIZACIÓN: Si agregara un --outargumento para agarrar para renderizar a un archivo HTML en lugar del navegador, ¿sería aceptable?
Joe

@ Joe, ¡por favor agrega esa opción!
bguiz

@McLeopold @bguiz acaba de implementar la --exportopción, que representa GFM y sus estilos en un solo archivo. ¿Responde esto la pregunta?
Joe

3
@McLeopold, Joe eliminó esto del parque al crear una solución simple y reutilizable, tal vez quiera darle la respuesta.
James McMahon

1
Github mismo usa Sundown . Ver stackoverflow.com/a/7694931/632951
Pacerier

Respuestas:


447

Escribí una pequeña CLI en Python y agregué soporte GFM. Se llama Grip (Github Readme Instant Preview) .

Instalarlo con:

$ pip install grip

Y para usarlo, simplemente:

$ grip

Luego visite localhost:5000para ver el readme.mdarchivo en esa ubicación.

También puede especificar su propio archivo:

$ grip CHANGES.md

Y cambiar de puerto:

$ grip 8080

Y, por supuesto, renderice específicamente Markit con sabor a GitHub, opcionalmente con contexto de repositorio:

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

Características notables:

  • Representa las páginas para que aparezcan exactamente como en GitHub
  • Bloques cercados
  • API de Python
  • Navegue entre los archivos vinculados (¡gracias, vladwing !) Agregados en 2.0
  • Exportar a un solo archivo (¡gracias, iliggio !) Agregado en 2.0
  • Nuevo: Leer stdiny exportar a stdout agregado en 3.0

Espero que esto ayude a alguien aquí. Compruébelo usted mismo .


1
¡Funciona realmente bien y no se puede superar la facilidad de instalación para Pythonistas!
RichVel

29
Este debería ser un primer éxito para la "vista previa de markith de github". Todo lo demás es complicado, no funciona o no hace todas las funciones de GitHub. gripfunciona directamente de la caja.
Bluu

1
@Houdini Ese problema está desactualizado. Flask admite 3.3, ver flask.pocoo.org/docs/python3 . Aquí hay un hilo de Github más reciente sobre el tema github.com/mitsuhiko/flask/issues/587 . Si hay otra dependencia que necesita actualizarse, siéntase libre de abrir un problema o una solicitud de extracción.
Joe

3
Cabe señalar que este paquete requiere una conexión a Internet activa y sus credenciales de autenticación de github (proporcionadas en la línea de comandos) si realiza más de 60 actualizaciones por hora.
leo

13
Como se mencionó anteriormente, no creo que esta sea una solución particularmente buena porque todo lo que hace va a Github y hace que Github renderice su Markdown. Requiere una conexión a Internet que funcione con acceso a Github, y si Github muere, esta herramienta deja de funcionar. Prefiero tener una solución completamente fuera de línea.
Jez

114

No he encontrado un método rápido y fácil para Markdown con sabor a GitHub, pero he encontrado una versión un poco más genérica: Pandoc . Convierte de / a varios formatos, incluidos Markdown, Rest, HTML y otros.

También he desarrollado un Makefilepara convertir todos los archivos .md a .html (en gran parte al ejemplo en Writing, Markdown y 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 $@

44
He estado usando "watch pandoc ..." para convertir continuamente un archivo de descuento a html, y la extensión "live reload" de Chrome para obtener en tiempo real la funcionalidad "permanecer donde me desplazan también" con esto, y funciona muy bien . chrome.google.com/webstore/detail/livereload/…
Brad Parks

1
Pandoc lee bien GFM pero no genera el mismo HTML que GitHub: por ejemplo, si tiene una <pre/>etiqueta de varias líneas en su fuente GFM, Pandoc colocará <br/>etiquetas para los saltos de línea, mientras que el renderizador de GitHub, elimina los espacios en blanco principales, de lo contrario parece dejar solo el contenido.
David Moles

1
¿Cómo se consigue un buen estilo en el HTML resultante? Mi salida todavía se procesa con Times New Roman, por ejemplo.
Desarrollador holístico el

Las instrucciones de instalación de Pandoc están aquí . En macOS:brew install pandoc
Master of Ducks

1
ni el gfmni el markdown_githubformato de entrada representan correctamente elementos como bloques de código.
user5359531

29

Quizás esto pueda ayudar:

gem install github-markdown

No existe documentación, pero la obtuve de la documentación de Gollum . Mirando rubydoc.info , parece que puedes usar:

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

en tu código Ruby. Puede ajustarlo fácilmente en un script para convertirlo en una utilidad de línea de comandos:

#!/usr/bin/env ruby

# render.rb
require 'github/markdown'

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

Ejecútalo con ./render.rb path/to/my/markdown/file.md. Tenga en cuenta que esto no es seguro para su uso en producción sin desinfección.


1
Gracias Jim, debido a ejemplos prácticamente inexistentes, me quedé atrapado en el paso requerido (reemplazando el guión con una barra oblicua) ..;)
plesatejvlk

Esto es genial si ya estás usando NPM. Tuve que usarlo, debido a que DOxygen me causaba problemas constantes con el marcado con sabor específicamente a github + exportación a HTML.
kayleeFrye_onDeck

¿se está ejecutando localmente o está enviando datos a la API de GitHub?
user5359531

28
pip3 install --user markdown
python3 -m markdown readme.md > readme.html

No maneja extensiones de GitHub, pero es mejor que nada. Creo que puede extender el módulo para manejar las adiciones de GitHub.


1
/ usr / bin / python: markdown es un paquete y no se puede ejecutar directamente
Kazimieras Aliulis

2
Salida HTML simple sin etiquetas elegantes.
Halil Kaskavalci

23

Probablemente no sea lo que desea, pero como mencionó Node.js: no pude encontrar una buena herramienta para obtener una vista previa de la documentación de GitHub Flavored Markdown en mi disco local antes de enviarlos a GitHub, así que hoy creé uno, basado en Node.js: https : //github.com/ypocat/gfms

Entonces, tal vez pueda reutilizar el showdown.js para su Wiki, si su pregunta aún es real. Si no, tal vez otras personas que enfrentan el mismo problema que yo encontrarán (tal como lo hice) esta pregunta y esta respuesta.


Hombre bien hecho. Me ahorra tener que recurrir a Ruby o Python cuando escribo una aplicación de nodo, lo cual es genial.
jedd.ahyoung

19

Para leer un archivo README.md en el terminal que uso:

pandoc README.md | lynx -stdin

Pandoc lo genera en formato HTML, que Lynx representa en su terminal.

Funciona muy bien: llena mi terminal, los accesos directos se muestran a continuación, puedo desplazarme y los enlaces funcionan. Sin embargo, solo hay un tamaño de fuente, pero los colores + sangría + alineación lo compensan.

Instalación:

sudo apt-get install pandoc lynx

1
La pregunta es específicamente sobre el uso de la línea de comandos. Antes de escribir su propio script ruby ​​(o egad node server), intente esto.
Cora Middleton

Exactamente esto funciona dentro de su terminal. O si su navegador favorito (¿escritorio?) Puede acceder al uso de esa carpeta pandoc readme.md -o readme.md.htmly abrir el archivo resultante.
Barry Staes

@ baerry-staes Sí, lo siento, espero que haya quedado claro que la suya fue mi respuesta favorita.
Cora Middleton

@JustinMiddleton sí, tengo eso, gracias. Mi comentario fue solo para agregar información adicional para usuarios de escritorio ... pensé que alguien algún día leer esto podría encontrarlo útil.
Barry Staes

1
He intentado con otros 5-6 lectores de consola md y esta ha sido la mejor solución. Acabo de agregar la función más básica a mi configuración para que sea un poco más rápido de usar. function md { pandoc $@ | lynx -stdin }
Russ Brown

17

GitHub tiene una API de Markdown que puedes usar.


55
jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < README.md | curl --data @- https://api.github.com/markdown > README.html
Vebjorn Ljosa

@VebjornLjosa * que * o grip... Tú elegiste. : P
aaaa

13

Uso marcado . Es compatible con GitHub Flavored Markdown, se puede utilizar como un módulo Node.js y desde la línea de comandos.

Un ejemplo sería:

$ marked -o hello.html
hello world
^D
$ cat hello.html
<p>hello world</p>

1
Me di cuenta de que esto no admite características como el resaltado de sintaxis para bloques de código y características más nuevas como listas de verificación. Pero bueno, ¡se hace casi todo el camino!
bguiz

Muy bien, lo único que me falta son algunos bordes para las tablas. Bueno, al menos puedo renderizarlos, esto es exactamente lo que necesito. Pipe in the GFM, pipe out HTML :)
Xandaros

Estoy confundido acerca de este ejemplo, ¿qué es ^D?
Mateo

10

Esto es principalmente un seguimiento de la respuesta de @ barry-staes para usar Pandoc . Homebrew también lo tiene, si estás en una Mac:

brew install pandoc

Pandoc admite GFM como formato de entrada a través del markdown_githubnombre.

Salida a archivo

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

Abierto en Lynx

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

Abrir en el navegador predeterminado en OS X

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

Integración TextMate

Siempre puede canalizar la selección actual o el documento actual a uno de los anteriores, como la mayoría de los editores le permiten hacer. También puede configurar fácilmente el entorno para que pandocreemplace el procesador Markdown predeterminado utilizado por el paquete Markdown .

Primero, cree un script de shell con los siguientes contenidos (lo llamaré ghmarkdown):

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

Luego puede establecer la TM_MARKDOWNvariable (en Preferencias → Variables) en /path/to/ghmarkdown, y reemplazará el procesador Markdown predeterminado.


10

Creé una herramienta similar a la funcionalidad de Vista previa de Atom, pero como una aplicación independiente. No estoy seguro de si esto es lo que está buscando, pero podría ser útil. - https://github.com/yoshuawuyts/vmd

vmd


¿Ustedes todavía están apoyando esto? Traté de instalar con NPM hoy, pero sin dados. > descargando electron-v0.36.9-win32-x64.zip> Error: certificado
autofirmado

1
Si, lo estamos! ¿En qué versión de npm / node ejecutó esto? - siéntase libre de abrir un problema sobre GH y veremos esto. ¡Gracias!
Yoshua Wuyts

8

pandocCon browserfunciona bien para mí.

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

Instalación (suponiendo que esté utilizando Mac OSX):

  • $ brew install pandoc

  • $ brew install browser

O en Debian / Ubuntu: apt-get install pandoc browser


1
apt-get isntall pandocservirá, no es necesario usar cosas locales inseguras como la cerveza.
Dominik George

1
@DominikGeorge hay un error tipográfico, es instalar , no isntall
Federico Tomassetti

11
@DominikGeorge no hay apt-get en macOS.
richrad

6

Consulte también https://softwareengineering.stackexchange.com/a/128721/24257 .


Si está interesado en cómo representamos [Github] los archivos de Markdown, puede consultar Redcarpet , nuestra interfaz Ruby para la biblioteca Sundown.

Ruby-script, que usa Redcarpet , será "utilidad de línea de comando", si tiene Ruby local


No tengo ideas - No escribo Ruby y no leí las fuentes de Redcarpet
Lazy Badger

@LazyBadger, Sundown es el analizador real (escrito en C). Redcarpet no es necesario.
Pacerier

6

Sobre la base de este comentario , escribí una línea para golpear la API de Github Markdown usando curly jq.

Pegue esta función bash en la línea de comando o en su ~/.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"
}

Y luego, para ver el HTML renderizado ejecutado en el navegador:

mdsee readme.md

Reemplace open "$HTMLFILE"con lynx "$HTMLFILE"si necesita una solución terminal pura.


4

GitHub ha desarrollado (desde entonces) un buen editor de texto modular llamado Atom (basado en Chromium y utiliza módulos Node.js para paquetes).

Un paquete preinstalado predeterminado Markdown Preview le permite mostrar su vista previa en una pestaña separada usando Ctrl+ Shift+ M.

No he probado su sintaxis completa, pero dado que proviene de GitHub, me sorprendería mucho si la sintaxis de la vista previa fuera diferente de la suya (bloques vallados que utilizan ~~~trabajo).

Ahora, aunque técnicamente no está basado en la línea de comandos, usa Node.js y se envía a un renderizador basado en DOM , lo que podría ayudar a cualquiera que intente renderizar HTML basado en sintaxis GitHub en un servidor web basado en Node.js, o simplemente editarlo / his README.md sin conexión.


1
En Atom puede instalar un paquete llamado gfm-pdf ( atom.io/packages/gfm-pdf ), que exporta su documento de rebajas a un documento HTML y / o PDF. Se requiere la biblioteca wkhtmltopdf .
spren9er


3

Existe una herramienta realmente agradable y simple para explorar documentos de GFM Markdown:

GFMS - Servidor de rebajas con sabor a Github

Es un servidor HTTP simple y liviano (no se necesita configuración) que puede iniciar en cualquier directorio que contenga archivos de descuento para examinarlos.

caracteristicas:

  • Soporte completo de GFM Markdown
  • Resaltado de la sintaxis del código fuente
  • Examinar archivos y directorios
  • Resultado atractivo (y hojas de estilo CSS configurables)
  • Exportar a PDF

3

Logré usar un script Ruby de una línea para ese propósito (aunque tenía que ir en un archivo separado). Primero, ejecute estos comandos una vez en cada máquina cliente desde la que enviará documentos:

gem install github-markup
gem install commonmarker

A continuación, instale este script en su imagen de cliente y llámelo render-readme-for-javadoc.rb:

require 'github/markup'

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

Finalmente, invocarlo así:

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

ETA: Esto no te ayudará con StackOverflow-taste Markdown, que parece estar fallando en esta respuesta.


Creo que esta es la respuesta "más cercana a la fuente" de todas ellas, ya que estas herramientas son las utilizadas por github.
memoselyk

3

Uso Pandoc con la opción --from=gfmde GitHub Flavored Markdown de esta manera:

$ pandoc my_file.md   --from=gfm -t html -o my_file.html

Con Pandoc 1.16.0.2 en Linux Mint 18 me da un error: pandoc: Unknown reader: gfm. Ir a 2.2.1 soluciona esto.
kidmose

Lo probé con Pandoc 2.1.2.
Asme Just

¿Cómo instalar 2.2.1 en ubuntu?
Alexander Mills

@AlexanderMills ¿Lo intentaste sudo apt install pandoc?
Asme Just

2

Mejorando la solución de @ barry-stae. Pegue este fragmento en ~ / .bashrc

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

Luego podemos ver rápidamente el archivo desde la línea de comandos. También funciona bien en sesiones SSH / Telnet.

mdviewer README.md

2

Adición tardía, pero showdownjs tiene una herramienta CLI que puede usar para analizar MD a HTML.


1

Encontré un sitio web que hará esto por usted: http://tmpvar.com/markdown.html . Pegue su Markdown y lo mostrará por usted. ¡Parece funcionar bien!

Sin embargo, no parece manejar la opción de resaltado de sintaxis para el código; es decir, la ~~~rubyfunción no funciona. Simplemente imprime 'ruby'.


tmpvar no parece hacer mejoras en la versión GFM como tablas
Greg

0

Mejorando las respuestas de @ barry-stae y @Sandeep para usuarios habituales de enlaces, agregaría lo siguiente a .bashrc:

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

No olvides instalar pandoc (y enlaces).


0

Basado en la respuesta de Jim Lim , instalé la gema GitHub Markdown. Eso incluía un script llamado gfm que toma un nombre de archivo en la línea de comando y escribe el HTML equivalente en la salida estándar. Lo modifiqué un poco para guardar el archivo en el disco y luego abrir el navegador estándar con 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)

1
Intenté esto con bloques cercados para Ruby y Pepino. Si bien las cercas ( ruby, pepino, etc.) parecen reconocerse como cercas (porque se representan en texto de ancho fijo), no hay resaltado de sintaxis. ¿Alguna idea de por qué?
Keith Bennett

0

Un enfoque 'rápido y sucio' es descargar las páginas HTML wiki usando la wgetutilidad, en lugar de clonarlo. Por ejemplo, así es como descargué el wiki de Hystrix desde GitHub (estoy usando 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

La primera llamada descargará la página de entrada wiki y todas sus dependencias. El segundo llamará a todas las subpáginas en él. Puede navegar ahora la wiki abriendo Netflix/Hystrix/wiki.1.html.

Tenga en cuenta que ambas llamadas a wgetson necesarias. Si solo ejecuta el segundo, perderá algunas dependencias necesarias para mostrar las páginas correctamente.


-1

Recientemente hice lo que quería, porque necesitaba generar documentación a partir de archivos Markdown y el estilo GitHub es bastante agradable. Intentalo. Está escrito en Node.js.

gfm


Lo sé, el módulo no se ha actualizado en 9 meses, ¿por qué rechazas una publicación anterior?
Gabriel Llamas
Al usar nuestro sitio, usted reconoce que ha leído y comprende nuestra Política de Cookies y Política de Privacidad.
Licensed under cc by-sa 3.0 with attribution required.