View or Test README files *md in a browser prior to pushing to an online repository for rendering

Question

Is there an application or way to render a README.md file in a browser on or offline? I am learning Markdown, and want instant feedback on some of my writing, as sometimes I forget a space or a blank line to achieve what I want, and it is cumbersome for me to commit and push to GitHub to see its rendering, not to mention the insane number of commits I'm creating for a small change.

Some have suggested setting up a PHP environment in your own server or virtual server, but I don't know how to do that (yet). I was thinking of an extension that if you opened an *.md file in your browser (I use Chrome predominately, but occasionally FF), it would look the same was as the frame in GitHub.\

I use TextMate and Sublime Text 2 to write the markdown, maybe they have a function I haven't seen/found on their site?

Solution 1

You can use the sublimetext-markdown-preview package for Sublime Text. It allows you to preview Markdown files on your browser. See the README.md for installation instructions.

Solution 2

Lazy answer

^{(for independent fast learners)}

• In Atom editor: Ctrl/Cmd+Shift+M
• In Sublime Text: there's a package to highlight Github Flavored MD, it renders live as you type within the very same editor, it may not look very pretty but at least you can instantly know if you are making mistakes. It's called knockdown. See this other question and my answer to know more about it.
  If you wan't to preview the pretty result in a browser before publishing you can use the Markdown Preview package.

---

Elaborate answer

^{(sublime-text novice red cross!)}

- Installing Package Control

1. Open sublime-text.
   _{[If you need this functionality available when you edit files on a directory owned by root or www-data ( i.e. /var/www/ ) you may want to open sublime with admin privileges using gksu sublime or similar and repeat every step]}

2. Activate sublime's console by pressing ctr+`
   _{[That is CONTROL key plus GRAVE ACCENT key (usually above the TAB key)]}

   

3. Copy-paste one of the following options to sublime console's prompt. _{(and press enter)}:

   If sublime-text 2:

   import urllib2,os,hashlib; h = '7183a2d3e96f11eeadd761d777e62404' + 'e330c659d4bb41d3bdf022e94cab3cd0'; pf = 'Package Control.sublime-package'; ipp = sublime.installed_packages_path(); os.makedirs( ipp ) if not os.path.exists(ipp) else None; urllib2.install_opener( urllib2.build_opener( urllib2.ProxyHandler()) ); by = urllib2.urlopen( 'http://sublime.wbond.net/' + pf.replace(' ', '%20')).read(); dh = hashlib.sha256(by).hexdigest(); open( os.path.join( ipp, pf), 'wb' ).write(by) if dh == h else None; print('Error validating download (got %s instead of %s), please try manual install' % (dh, h) if dh != h else 'Please restart Sublime Text to finish installation')
   

   If sublime-text 3:

   import urllib.request,os,hashlib; h = '7183a2d3e96f11eeadd761d777e62404' + 'e330c659d4bb41d3bdf022e94cab3cd0'; pf = 'Package Control.sublime-package'; ipp = sublime.installed_packages_path(); urllib.request.install_opener( urllib.request.build_opener( urllib.request.ProxyHandler()) ); by = urllib.request.urlopen( 'http://sublime.wbond.net/' + pf.replace(' ', '%20')).read(); dh = hashlib.sha256(by).hexdigest(); print('Error validating download (got %s instead of %s), please try manual install' % (dh, h)) if dh != h else open(os.path.join( ipp, pf), 'wb' ).write(by)
   

   

4. Close sublime when the console prints back a message saying "Please restart Sublime Text to finish installation" _{(usually almost instantaneous)}. Open sublime-text again.

5. Once you restarted sublime-text, the rest is easy, see "Fast Answer" _(above), or read on.

About using Package Control

What you just installed adds a new bunch of commands to your Palette and opens the door to a wonderful world of community contributed plugins; a way to extend sublime's functionality by other people or by yourself! (share your code!).
Now lets use it to install Markdown Preview.

1. You can access Package Controll simply by pressing ctr+shift+P, and typing Package Control, pc, pack (or anything similar thanks to the fuzzy search feature of the command palette), in this case search the right command by writing Package Control: Install Package (or just pi).
   _{(If something goes wrong you can always Remove Package)}.

   

2. To see all the available packages just enter or click on it. Sublime will search for all the registered packages and will even check and show for you only the ones that are compatible with your version of sublime-text, you'll have to wait a few seconds.
   _{(or less than a second, depending on your internet+computer latency+speed)}.

   

3. Now search for and select Markdown Preview.

   

4. After you hit Enter or click on it it will take a brief moment to install.

   

   That's it, it just works.

- How to use it you ask?

To preview your pretty markdown in your default browser:

1. Inside sublime-text and with a .md file opened, press ctr+shift+P again.

2. Search for Markdown Preview and enter or click on it.
   ^{(There are many options, I just like github flavor the most :D)}

   

... pics, else it shant have come to pass:

^{(it totally works! here's the evidence)}

presto!
You just took one further step to be a sublime-text master, I hope my answer helped you

Solution 3

You can install the python package index pip and then install an application called grip that will serve the .md file on a localhost port. Its very easy once its been installed.

sudo easy_install pip
sudo pip install grip

Then just run:

grip

In the root directory of the .md file.

Solution 4

There's a Chrome plugin to do exactly this.

Markdown Preview

Converts and previews markdown files (.md, .markdown) to HTML right inside Chrome.

Solution 5

If you're on OSX / Linux and don't mind the command line, here's a simple script that opens the rendered markdown in a browser:

#!/usr/bin/env bash

OUTPUT=/tmp/$(basename $1).html
markdown $1 > $OUTPUT
open $OUTPUT
# FIXME: Avoid deleting before opening; possible to use `wait`
# instead?
sleep 1
rm $OUTPUT

You might need to substitute the open command for something that works on your flavour of Linux, e.g. firefox $OUTPUT.

The sleep 1 is just a hack to prevent the file from being removed before the browser has time to read it; I'm sure a more proficient bash hacker can substitute it with something less ugly ;)

View more solutions

Comments

[user456584]

There's also Markdown Preview Plus.

[dwanderson]

Unfortunately, Markdown Preview seems to be a little too finnicky (or just uses a different style than Github-flavored Markdown?) - it wasn't formatting code blocks and lists correctly, even though Github rendered them just fine.

[dwanderson]

This answer needs to get bumped higher - absurdly simple to use, interacts with Github directly, and works very well.

[sage]

I recommend using a virtualenv instead of installing and then this is perfect for me.

[XavierStuvw]

Also available as a package in Ubuntu at packages.ubuntu.com/…. You can install it straight away with sudo apt install grip, and man grip will provide most usage information you need. It provides a localhost-type URL that you can open in the browser, showing the rendered md. The view in the browser gets refreshed every time you save the source md file in a text editor.