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

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.

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 .

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 $@

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.

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.

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.

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

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

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>

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.

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

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

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

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.

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.

Ma dernière solution a été d'utiliser Python Markdown . J'ai roulé ma propre extension qui a fixé les blocs de clôture.

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

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.

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

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

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

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».

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).

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)

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.

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