Existe-t-il un utilitaire de ligne de commande pour rendre le Markdown aromatisé GitHub?

414

Je me demande s'il existe un utilitaire de ligne de commande pour prendre un fichier Markdown aromatisé GitHub et le rendre au format HTML.

J'utilise un wiki GitHub pour créer du contenu de site Web. J'ai cloné le référentiel sur mon serveur et je voudrais ensuite le traiter en HTML standard. Il est important pour moi que ce qui apparaît sur GitHub soit exactement à quoi il devrait ressembler pour mon site Web. J'aimerais aussi vraiment utiliser les blocs clôturés avec ~~~, donc je préfère ne pas utiliser uniquement la syntaxe Markdown standard.

J'ai examiné un peu l'aperçu en direct de JavaScript en pensant que je pouvais le connecter à Node.js, mais ils disent qu'il est obsolète. J'ai regardé le référentiel redcarpet, mais il ne semble pas avoir d'interface de ligne de commande.

J'ai toutefois lancé ma propre solution, car aucune solution ici n'est clairement meilleure que les autres, je vais laisser la question sans réponse sélectionnée.

McLeopold
la source
2
RE: UPDATE: Si j'ajoutais un --outargument à saisir pour effectuer un rendu dans un fichier HTML au lieu du navigateur, cela serait-il acceptable?
Joe
@Joe, veuillez ajouter cette option!
bguiz
@McLeopold @bguiz vient de déployer l' --exportoption, qui rend GFM et ses styles dans un seul fichier. Est-ce que cela répond à la question?
Joe
3
@McLeopold, Joe a mis cela hors du parc en créant une solution simple et réutilisable, pourrait vouloir lui donner la réponse.
James McMahon le
1
Github lui-même utilise Sundown . Voir stackoverflow.com/a/7694931/632951
Pacerier

Réponses:

447

J'ai écrit une petite CLI en Python et ajouté le support GFM. Cela s'appelle Grip (Github Readme Instant Preview) .

Installez-le avec:

$ pip install grip

Et pour l'utiliser, simplement:

$ grip

Ensuite, visitez localhost:5000pour afficher le readme.mdfichier à cet endroit.

Vous pouvez également spécifier votre propre fichier:

$ grip CHANGES.md

Et changez de port:

$ grip 8080

Et bien sûr, restituez spécifiquement GitHub-Flavored Markdown, éventuellement avec le contexte du référentiel:

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

Caractéristiques notables:

  • Rend les pages pour apparaître exactement comme sur GitHub
  • Blocs clôturés
  • API Python
  • Naviguez entre les fichiers liés (merci, vladwing !) Ajoutés dans 2.0
  • Exporter vers un seul fichier (merci, iliggio !) Ajouté en 2.0
  • Nouveau: lire stdinet exporter vers stdout ajouté en 3.0

J'espère que cela aide quelqu'un ici. Vérifiez-le .

Joe
la source
1
Fonctionne très bien et vous ne pouvez pas battre la facilité d'installation pour Pythonistas!
RichVel
29
Cela devrait être un premier succès pour "aperçu du démarquage github". Tout le reste est compliqué, ne fonctionne pas ou ne fait pas toutes les fonctionnalités de GitHub. gripfonctionne dès la sortie de la boîte.
Bluu
1
@Houdini Ce problème est obsolète. Flask prend en charge 3.3, voir flask.pocoo.org/docs/python3 . Voici un fil Github plus récent sur le sujet github.com/mitsuhiko/flask/issues/587 . S'il y a une autre dépendance à mettre à jour, n'hésitez pas à ouvrir un problème ou une demande d'extraction.
Joe
3
Il convient de noter que ce package nécessite une connexion Internet active et vos informations d'authentification github (fournies sur la ligne de commande) si vous effectuez plus de 60 rafraîchissements par heure.
leo
13
Comme mentionné précédemment, je ne pense pas que ce soit une solution particulièrement intéressante, car tout ce qu'il fait, il va à Github et obtient Github pour rendre votre Markdown. Il nécessite une connexion Internet fonctionnelle avec accès à Github, et si Github meurt, cet outil cesse de fonctionner. Je préfère avoir une solution complètement hors ligne.
Jez
114

Je n'ai pas trouvé de méthode rapide et facile pour Markdown au goût de GitHub, mais j'ai trouvé une version légèrement plus générique - Pandoc . Il convertit de / vers un certain nombre de formats, y compris Markdown, Rest, HTML et autres.

J'ai également développé un Makefilepour convertir tous les fichiers .md en .html (en grande partie à l'exemple de Writing, Markdown et 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
la source
4
j'ai utilisé "watch pandoc ..." pour convertir en continu un fichier de démarque en html, et l'extension chrome "live reload" pour obtenir en temps réel la fonctionnalité "rester là où je défile aussi" avec cela, et cela fonctionne très bien . chrome.google.com/webstore/detail/livereload/…
Brad Parks
1
Pandoc lit très bien GFM mais il ne génère pas le même code HTML que GitHub - par exemple, si vous avez une <pre/>balise multiligne dans votre source GFM, Pandoc placera des <br/>balises pour les sauts de ligne, tandis que le rendu de GitHub, cependant il dépouille les espaces blancs de premier plan, semble autrement laisser le contenu seul.
David Moles
1
Comment peut-on obtenir un style agréable sur le HTML résultant? Ma sortie est toujours rendue avec Times New Roman, par exemple.
Développeur holistique
Les instructions d'installation de Pandoc sont ici . Sur macOS:brew install pandoc
Master of Ducks du
1
ni le gfmni les markdown_githubformats d'entrée ne rendent correctement les choses comme les blocs de code.
user5359531
29

Cela pourrait peut-être aider:

gem install github-markdown

Aucune documentation n'existe, mais je l'ai obtenue de la documentation de gollum . En regardant rubydoc.info , il semble que vous pouvez utiliser:

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

dans votre code Ruby. Vous pouvez envelopper cela facilement dans un script pour le transformer en un utilitaire de ligne de commande:

#!/usr/bin/env ruby

# render.rb
require 'github/markdown'

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

Exécutez-le avec ./render.rb path/to/my/markdown/file.md. Notez que ce n'est pas sûr pour une utilisation en production sans désinfection.

James Lim
la source
1
Merci Jim, en raison d'exemples pratiquement inexistants, j'étais coincé à l'étape de besoin (remplacer le tiret par une barre oblique l'a fait) ..;)
plesatejvlk
C'est très bien si vous utilisez déjà NPM. Je devais l'utiliser, à cause de DOxygen me causant des problèmes constants avec le démarquage spécifiquement aromatisé au github + l'exportation au format HTML.
kayleeFrye_onDeck
Est-ce que cela fonctionne localement ou envoie-t-il des données à l'API GitHub?
user5359531
28
pip3 install --user markdown
python3 -m markdown readme.md > readme.html

Il ne gère pas les extensions GitHub, mais c'est mieux que rien. Je pense que vous pouvez étendre le module pour gérer les ajouts de GitHub.

Gringo Suave
la source
1
/ usr / bin / python: le démarquage est un package et ne peut pas être exécuté directement
Kazimieras Aliulis
2
Sortie HTML simple sans balises fantaisie.
Halil Kaskavalci
23

Probablement pas ce que vous voulez, mais puisque vous avez mentionné Node.js: je n'ai pas pu trouver un bon outil pour prévisualiser la documentation de GitHub Flavored Markdown sur mon lecteur local avant de les valider sur GitHub, alors aujourd'hui j'en ai créé un, basé sur Node.js: https : //github.com/ypocat/gfms

Vous pouvez donc peut-être réutiliser le showdown.js pour votre Wiki, si votre question est toujours d'actualité. Sinon, peut-être que d'autres personnes confrontées au même problème que moi trouveront (tout comme moi) cette question et cette réponse.

youurayy
la source
Bien joué, mec. Cela m'évite d'avoir à recourir à Ruby ou Python lorsque j'écris une application de noeud, ce qui est génial.
jedd.ahyoung
19

Pour lire un fichier README.md dans le terminal que j'utilise:

pandoc README.md | lynx -stdin

Pandoc le produit au format HTML, que Lynx rend dans votre terminal.

Cela fonctionne très bien: il remplit mon terminal, les raccourcis sont indiqués ci-dessous, je peux faire défiler et les liens fonctionnent! Il n'y a qu'une seule taille de police, mais les couleurs + retrait + alignement compensent cela.

Installation:

sudo apt-get install pandoc lynx
Barry Staes
la source
1
La question concerne spécifiquement l'utilisation de la ligne de commande. Avant d'écrire votre propre script ruby ​​(ou serveur de nœuds egad), essayez ceci.
Cora Middleton
Cela fonctionne exactement à l'intérieur de votre terminal. Ou si votre navigateur préféré (de bureau?) Peut accéder à ce dossier, utilisez pandoc readme.md -o readme.md.htmlet ouvrez le fichier résultant.
Barry Staes
@ baerry-staes Oui, désolé, j'espère qu'il était clair que la vôtre était ma réponse préférée.
Cora Middleton
@JustinMiddleton oui j'ai compris, merci. Mon commentaire était juste d'ajouter quelques informations supplémentaires pour les utilisateurs de bureau .. J'ai pensé qu'un jour quelqu'un lisant cela pourrait le trouver utile.
Barry Staes
1
J'ai essayé environ 5-6 autres lecteurs de console md et cela a été de loin la meilleure solution. Je viens d'ajouter la fonction la plus basique à ma configuration pour la rendre un peu plus rapide à utiliser. function md { pandoc $@ | lynx -stdin }
Russ Brown
17

GitHub dispose d' une API Markdown que vous pouvez utiliser.

kehers
la source
5
jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < README.md | curl --data @- https://api.github.com/markdown > README.html
Vebjorn Ljosa
@VebjornLjosa * que * ou grip... Vous avez choisi. : P
yyny
13

Utilisez marqué . Il prend en charge GitHub Flavored Markdown, peut être utilisé comme module Node.js et à partir de la ligne de commande.

Un exemple serait:

$ marked -o hello.html
hello world
^D
$ cat hello.html
<p>hello world</p>
zemirco
la source
1
J'ai remarqué que cela ne prend pas en charge des fonctionnalités telles que la mise en évidence de la syntaxe pour les blocs de code et les fonctionnalités plus récentes telles que les listes de contrôle. Mais bon, ça fait presque tout le chemin!
bguiz
Très bien, la seule chose qui me manque, c'est quelques bordures pour les tables. Eh bien, au moins je peux les rendre du tout, c'est à peu près exactement ce dont j'ai besoin. Pipe dans la GFM, pipe HTML :)
Xandaros
Je suis confus à propos de cet exemple, qu'est-ce que c'est ^D?
Matthew
10

Il s'agit principalement d'un suivi de la réponse de @ barry-staes pour l'utilisation de Pandoc . Homebrew l'a aussi, si vous êtes sur un Mac:

brew install pandoc

Pandoc prend en charge GFM comme format d'entrée via le markdown_githubnom.

Sortie dans un fichier

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

Ouvrir dans Lynx

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

Ouvrir dans le navigateur par défaut sous OS X

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

Intégration TextMate

Vous pouvez toujours diriger la sélection ou le document actuel vers l'un des éléments ci-dessus, comme la plupart des éditeurs le permettent. Vous pouvez également configurer facilement l'environnement afin qu'il pandocremplace le processeur Markdown par défaut utilisé par le bundle Markdown .

Tout d'abord, créez un script shell avec le contenu suivant (je l'appellerai ghmarkdown):

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

Vous pouvez ensuite définir la TM_MARKDOWNvariable (dans Préférences → Variables) sur /path/to/ghmarkdown, et elle remplacera le processeur Markdown par défaut.

Cora Middleton
la source
10

J'ai créé un outil similaire à la fonctionnalité Aperçu d'Atom, mais en tant qu'application autonome. Je ne sais pas si c'est ce que vous recherchez, mais cela pourrait être utile. - https://github.com/yoshuawuyts/vmd

vmd

Yoshua Wuyts
la source
Vous soutenez toujours cela? J'ai essayé d'installer avec NPM aujourd'hui, mais pas de dés. > téléchargement de electron-v0.36.9-win32-x64.zip> Erreur: certificat auto-signé
kayleeFrye_onDeck
1
Oui, nous le sommes! Sur quelle version de npm / node avez-vous exécuté ceci? - n'hésitez pas à ouvrir un problème sur GH et nous allons y jeter un œil. Merci!
Yoshua Wuyts
8

pandocavec browserfonctionne bien pour moi.

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

Installation (en supposant que vous utilisez Mac OSX):

  • $ brew install pandoc

  • $ brew install browser

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

binaire
la source
1
apt-get isntall pandocfera l'affaire, pas besoin d'utiliser des trucs locaux non sécurisés comme de la bière.
Dominik George
1
@DominikGeorge il y a une faute de frappe, c'est installer , pas pas du tout
Federico Tomassetti
11
@DominikGeorge il n'y a pas d'apt-get sur macOS.
richrad
6

Voir également https://softwareengineering.stackexchange.com/a/128721/24257 .


Si vous êtes intéressé par la façon dont nous [Github] rendons les fichiers Markdown, vous voudrez peut-être consulter Redcarpet , notre interface Ruby à la bibliothèque Sundown.

Ruby-script, qui utilise Redcarpet , sera un "utilitaire de ligne de commande", si vous avez Ruby local

Blaireau paresseux
la source
Je n'ai pas d'idées - je n'écris pas Ruby et je n'ai pas lu les sources de Redcarpet
Lazy Badger
@LazyBadger, Sundown est l'analyseur réel (écrit en C). Redcarpet n'est pas nécessaire.
Pacerier
6

Sur la base de ce commentaire, j'ai écrit un one-liner pour frapper l' API Github Markdown en utilisant curlet jq.

Collez cette fonction bash sur la ligne de commande ou dans votre ~/.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"
}

Et puis pour voir le rendu HTML exécuté dans le navigateur:

mdsee readme.md

Remplacez-le open "$HTMLFILE"par lynx "$HTMLFILE"si vous avez besoin d'une solution terminale pure.

notpeter
la source
4

GitHub a (depuis) ​​développé un bel éditeur de texte modulaire appelé Atom (basé sur Chromium et utilise des modules Node.js pour les packages).

Un package préinstallé par défaut Markdown Preview vous permet d'afficher votre aperçu dans un onglet séparé à l'aide de Ctrl+ Shift+ M.

Je n'ai pas testé sa syntaxe complète, mais comme il provient de GitHub, je serais très surpris si la syntaxe de l'aperçu était différente de la leur (blocs clôturés utilisant du ~~~travail).

Maintenant, bien qu'il ne soit pas techniquement basé sur la ligne de commande, il utilise Node.js et sort vers un moteur de rendu basé sur DOM , ce qui pourrait aider toute personne essayant de rendre le code HTML basé sur la syntaxe GitHub sur un serveur Web basé sur Node.js, ou simplement la modifier / son fichier README.md hors ligne.

Que
la source
1
Dans Atom, vous pouvez installer un package appelé gfm-pdf ( atom.io/packages/gfm-pdf ), qui exporte votre document de démarque vers un document HTML et / ou PDF. La bibliothèque wkhtmltopdf est requise.
spren9er
3

Il existe un outil très agréable et simple pour parcourir les documents GFM Markdown:

GFMS - Github Flavored Markdown Server

C'est un serveur HTTP simple et léger (aucune configuration nécessaire) que vous pouvez démarrer dans n'importe quel répertoire contenant des fichiers de démarque pour les parcourir.

Fonctionnalités:

  • Prise en charge complète de GFM Markdown
  • Mise en évidence de la syntaxe du code source
  • Parcourir des fichiers et des répertoires
  • Belle sortie (et feuilles de style CSS configurables)
  • Exporter au format PDF
Pawel Wiejacha
la source
3

J'ai réussi à utiliser un script Ruby d'une ligne à cet effet (bien qu'il devait être placé dans un fichier séparé). Tout d'abord, exécutez ces commandes une fois sur chaque machine cliente à partir de laquelle vous pousserez les documents:

gem install github-markup
gem install commonmarker

Ensuite, installez ce script dans votre image client et appelez-le render-readme-for-javadoc.rb:

require 'github/markup'

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

Enfin, invoquez-le comme ceci:

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

ETA: Cela ne vous aidera pas avec StackOverflow-flavour Markdown, qui semble échouer dans cette réponse.

Pr0methean
la source
Je pense que c'est la réponse "la plus proche de la source" de tous, car ces outils sont ceux utilisés par github.
memoselyk du
3

J'utilise Pandoc avec l'option --from=gfmpour GitHub Flavored Markdown comme ceci:

$ pandoc my_file.md   --from=gfm -t html -o my_file.html
Asme Just
la source
Avec pandoc 1.16.0.2 sur Linux Mint 18 je reçois une erreur: pandoc: Unknown reader: gfm. Aller à 2.2.1 résout ce problème.
kidnapper le
Je l'ai testé avec Pandoc 2.1.2.
Asme Just
comment installer 2.2.1 sur ubuntu?
Alexander Mills
@AlexanderMills Avez-vous essayé sudo apt install pandoc?
Asme Just
2

Amélioration de la solution de @ barry-stae. Collez cet extrait dans ~ / .bashrc

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

Ensuite, nous pouvons afficher rapidement le fichier à partir de la ligne de commande. Fonctionne également très bien sur les sessions SSH / Telnet.

mdviewer README.md
Sandeep
la source
2

Ajout tardif mais showdownjs dispose d'un outil CLI que vous pouvez utiliser pour analyser MD en HTML.

Tivie
la source
1

J'ai trouvé un site Web qui le fera pour vous: http://tmpvar.com/markdown.html . Collez votre Markdown et il l'affichera pour vous. Cela semble très bien fonctionner!

Cependant, il ne semble pas gérer l'option de coloration syntaxique pour le code; c'est-à-dire que la ~~~rubyfonctionnalité ne fonctionne pas. Il imprime juste «rubis».

JESii
la source
tmpvar ne semble pas faire d'améliorations de la version GFM comme les tables
Greg
0

En améliorant les réponses @ barry-stae et @Sandeep pour les utilisateurs réguliers d'elinks, vous ajouteriez ce qui suit à .bashrc:

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

N'oubliez pas d'installer pandoc (et elinks).

daBertl
la source
0

Sur la base de la réponse de Jim Lim , j'ai installé la gemme GitHub Markdown. Cela comprenait un script appelé gfm qui prend un nom de fichier sur la ligne de commande et écrit le code HTML équivalent dans la sortie standard. J'ai légèrement modifié cela pour enregistrer le fichier sur le disque, puis pour ouvrir le navigateur standard avec 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
la source
1
J'ai essayé cela avec des blocs clôturés pour Ruby et Cucumber. Bien que les clôtures ( ruby, concombre, etc.) semblent être reconnues comme des clôtures (car elles sont rendues en texte à largeur fixe), il n'y a pas de coloration syntaxique. Une idée pourquoi?
Keith Bennett
0

Une approche «rapide et sale» consiste à télécharger les pages HTML wiki à l'aide de l' wgetutilitaire, au lieu de le cloner. Par exemple, voici comment j'ai téléchargé le wiki Hystrix depuis GitHub (j'utilise 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

Le premier appel téléchargera la page d'entrée du wiki et toutes ses dépendances. La seconde appellera toutes les sous-pages sur elle. Vous pouvez maintenant parcourir le wiki en ouvrant Netflix/Hystrix/wiki.1.html.

Notez que les deux appels à wgetsont nécessaires. Si vous exécutez simplement le second, vous manquerez certaines dépendances nécessaires pour afficher correctement les pages.

Luis Rodero-Merino
la source
-1

J'ai récemment fait ce que vous vouliez, car j'avais besoin de générer de la documentation à partir de fichiers Markdown et le style GitHub est plutôt sympa. Essayez-le. Il est écrit en Node.js.

gfm

Gabriel Llamas
la source
Je sais, le module n'a pas été mis à jour depuis 9 mois, pourquoi votez-vous pour un ancien post?
Gabriel Llamas