Is there a command line utility for rendering GitH

Question

I'm wondering if there is a command line utility for taking a GitHub flavored Markdown file and rendering it to HTML.

I'm using a GitHub wiki to create website content. I've cloned the repository on my server and would then like to process it into regular HTML. It's important to me that what appears on GitHub is exactly how it should look for my website. I'd also really like to use the fenced blocks with ~~~, so I'd rather not use standard Markdown syntax only.

I've looked a bit into the JavaScript live preview thinking I could hook it into Node.js, but they say it is deprecated. I've looked at the redcarpet repository, but it doesn't look like it has a command line interface.

I rolled my own solution, however, since no solution here is clearly better than the others, I'll leave the question without a selected answer.

Answer 1

I created a tool similar to Atom's Preview functionality, but as a standalone application. Not sure if this is what you're looking for, but it might be helpful. -- https://github.com/yoshuawuyts/vmd

Answer 2

I wrote a small CLI in Python and added GFM support. It's called Grip (Github Readme Instant Preview).

Install it with:

$ pip install grip

And to use it, simply:

$ grip

Then visit localhost:5000 to view the readme.md file at that location.

You can also specify your own file:

$ grip CHANGES.md

And change port:

$ grip 8080

And of course, specifically render GitHub-Flavored Markdown, optionally with repository context:

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

Notable features:

• Renders pages to appear exactly like on GitHub
• Fenced blocks
• Python API
• Navigate between linked files (thanks, vladwing!) added in 2.0
• Export to a single file (thanks, iliggio!) added in 2.0
• New: Read from stdin and export to stdout added in 3.0

Hope this helps someone here. Check it out.

Answer 3

I use Pandoc with the option --from=gfm like this:

$ pandoc markdown-sample.md   --from=gfm -t html -o markdown-sample.html

Answer 4

Based on Jim Lim's answer, I installed the GitHub Markdown gem. That included a script called gfm that takes a filename on the command line and writes the equivalent HTML to standard output. I modified that slightly to save the file to disk and then to open the standard browser with 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)

Answer 5

GitHub has (since) developed a nice modular text editor called Atom (based on Chromium and uses Node.js modules for packages).

A default preinstalled package Markdown Preview lets you display your preview in a separate tab using Ctrl + Shift + M.

I haven't tested its full syntax, but since it's coming from GitHub, I'd be highly surprised if the preview's syntax was different from theirs (fenced blocks using ~~~ work).

Now, while it's not technically command-line based, it uses Node.js and outputs to a DOM-based renderer, which might help anyone trying to render GitHub syntax-based HTML on a Node.js-based webserver, or just edit her/his README.md offline.

Answer 6

Building on this comment I wrote a one-liner to hit the Github Markdown API using curl and jq.

Paste this bash function onto the command line or into your ~/.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"
}

And then to see the rendered HTML in-browser run:

mdsee readme.md

Replace open "$HTMLFILE" with lynx "$HTMLFILE" if you need a pure terminal solution.