Is there a command line utility for rendering GitHub flavored Markdown?

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.

  • How to clone previous repo version to local machine?
  • Git clone with password @
  • Move a file to a new folder, keeping Git history
  • How does git, for example, create the database they use?
  • Does svn have a `revert-all` command?
  • git and system variables on Windows
  • 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.

  • How do I do basic authentication with RestClient?
  • How to squash a commit made in the GitHub website?
  • How do I re-play my commits of a local git repo, on top of a project I forked on github.com?
  • Git: how to move a branch between repositories
  • A clean system for github pages with local plugins
  • How do I save a `git reset`
  • 22 Solutions collect form web for “Is there a command line utility for rendering GitHub flavored Markdown?”

    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.

    I’ve not found a quick and easy method for GitHub-flavoured Markdown, but I have found a slightly more generic version – Pandoc. It converts from/to a number of formats, including Markdown, Rest, HTML and others.

    I’ve also developed a Makefile to convert all .md files to .html (in large part to the example at Writing, Markdown and Pandoc):

    # 'Makefile'
    MARKDOWN = pandoc --from markdown_github --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 $@
    

    Maybe this might help:

    gem install github-markdown
    

    No documentation exists, but I got it from the gollum documentation. Looking at rubydoc.info, it looks like you can use:

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

    in your Ruby code. You can wrap that easily in a script to turn it into a command line utility:

    #!/usr/bin/env ruby
    
    # render.rb
    require 'github/markdown'
    
    puts GitHub::Markdown.render_gfm File.read(ARGV[0])
    

    Execute it with ./render.rb path/to/my/markdown/file.md. Note that this is not safe for use in production without sanitization.

    sudo pip install markdown
    python -m markdown readme.md > readme.html
    

    It doesn’t handle GitHub extensions, but it is better than nothing. I believe you can extend the module to handle the GitHub additions.

    Probably not what you want, but since you mentioned Node.js: I could not find a good tool to preview GitHub Flavored Markdown documentation on my local drive before committing them to GitHub, so today I created one, based on Node.js: https://github.com/ypocat/gfms

    So perhaps you can reuse the showdown.js from it for your Wiki, if your question is still actual. If not, maybe other people facing the same problem as I did will find (just as I did) this question and this answer to it.

    Use marked. It supports GitHub Flavored Markdown, can be used as a Node.js module and from the command line.

    An example would be:

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

    GitHub has a Markdown API you can use.

    To read a README.md file in the terminal I use:

    pandoc README.md | lynx -stdin
    

    Pandoc outputs it in HTML format, which Lynx renders in your terminal.

    It works great: It fills my terminal, shortcuts are shown below, I can scroll through, and the links work!
    There is only one font size though, but the colors + indentation + alignment make up for that.

    Installation:

    sudo apt-get install pandoc lynx
    

    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

    vmd

    This is mostly a follow-on to @barry-staes’s answer for using Pandoc. Homebrew has it as well, if you’re on a Mac:

    brew install pandoc
    

    Pandoc supports GFM as an input format via the markdown_github name.

    Output to file

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

    Open in Lynx

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

    Open in the default browser on OS X

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

    TextMate Integration

    You can always pipe the current selection or current document to one of the above, as most editors allow you to do. You can also easily configure the environment so that pandoc replaces the default Markdown processor used by the Markdown bundle.

    First, create a shell script with the following contents (I’ll call it ghmarkdown):

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

    You can then set the TM_MARKDOWN variable (in Preferences→Variables) to /path/to/ghmarkdown, and it will replace the default Markdown processor.

    pandoc with browser works well for me.

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

    Installation (Assuming you are using Mac OSX):

    • $ brew install pandoc

    • $ brew install browser

    Or on Debian/Ubuntu: apt-get install pandoc browser

    Also see https://softwareengineering.stackexchange.com/a/128721/24257.


    If you’re interested in how we [Github] render Markdown files, you might want to check out Redcarpet, our Ruby interface to the Sundown library.

    Ruby-script, which use Redcarpet, will be “command line utility”, if you’ll have local Ruby

    My final solution was to use Python Markdown. I rolled my own extension that fixed the fence blocks.

    There is a really nice and simple tool for browsing GFM Markdown documents:

    GFMS – Github Flavored Markdown Server

    It’s simple and lightweight (no configuration needed) HTTP server you can start in any directory containing markdown files to browse them.

    Features:

    • Full GFM Markdown support
    • Source code syntax highlighting
    • Browsing files and directories
    • Nice looking output (and configurable CSS stylesheets)
    • Export to PDF

    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.

    Improving upon @barry-stae’s solution. Stick this snippet in ~/.bashrc

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

    Then we can quickly view the file from the command-line. Also works nicely over SSH/Telnet sessions.

    mdviewer README.md
    

    I found a website that will do this for you: http://tmpvar.com/markdown.html. Paste in your Markdown, and it’ll display it for you. It seems to work just fine!

    However, it doesn’t seem to handle the syntax highlighting option for code; that is, the ~~~ruby feature doesn’t work. It just prints ‘ruby’.

    Late addition but showdownjs has a CLI tool you can use to parse MD to HTML.

    Improving upon @barry-stae and @Sandeep answers for regular users of elinks you would add the following to .bashrc:

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

    Don’t forget to install pandoc (and elinks).

    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)
    

    A ‘quick-and-dirty’ approach is to download the wiki HTML pages using the wget utility, instead of cloning it. For example, this is how I downloaded the Hystrix wiki from GitHub (I’m using 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
    

    The first call will download the wiki entry page and all its dependencies. The second one will call all sub-pages on it. You can browse now the wiki by opening Netflix/Hystrix/wiki.1.html.

    Note that both calls to wget are necessary. If you just run the second one then you will miss some dependencies required to show the pages properly.

    I recently made what you want, because I was in need to generate documentation from Markdown files and the GitHub style is pretty nice. Try it. It is written in Node.js.

    gfm

    Git Baby is a git and github fan, let's start git clone.