Grab a Markdown file and shove that fucker inside a styled up HTML file.

This is the Readme.md file

All sorts of important shit should go here about your project

==============

What is it?

preview_markdown_locally illustrates how to give your repository a README.html file that renders your README.md locally so can iterate and preview before you push up to Github.

To see it in action, clone this repository and drop it under any static-file-serving web server. Then navigate to README.html.

If you're seeing this and you're not on github.com, you already have. Congrats ):

The README.html contains a hotlink to Github's bundled stylesheet, and the containers are named such that it'll apply properly. This helps me get a better picture of what the documentation will look like on github.com. That said, it's totally optional and you may have other HTML & CSS that you prefer.

Caveats

Github uses Github Flavored Markdown (GFM). The included markdown.js does not contain the GFM extensions. Thus, you might see slight differences when rendered on Github.

<!DOCTYPE html>
<html>
<head>
  <link href="bundle_github.css" rel="stylesheet" type="text/css">
</head>
<body>
<div class="site">
  <div id="slider">
    <div class="frames">
      <div class="frame frame-center">
        <div id="readme" class="announce">
          <div id="markdown" class="wikistyle"></div>
        </div>
      </div>
    </div>
  </div>
</div>
<script type="text/javascript">
// Released under MIT license
// Copyright (c) 2009-2010 Dominic Baggott
// Copyright (c) 2009-2010 Ash Berlin
// Copyright (c) 2011 Christoph Dorn <christoph@christophdorn.com> (https://www.christophdorn.com)
(function(b){function e(a){var b=0,c=-1;while((c=a.indexOf("\n",c+1))!=-1)b++;return b}function f(a,b){function e(a){this.len_after=a,this.name="close_"+b}var c=a+"_state",d=a=="strong"?"em_state":"strong_state";return function(f,g){if(this[c][0]==b)return this[c].shift(),[f.length,new e(f.length-b.length)];var h=this[d].slice(),i=this[c].slice();this[c].unshift(b);var j=this.processInline(f.substr(b.length)),k=j[j.length-1],l=this[c].shift();if(k instanceof e){j.pop();var m=f.length-k.len_after;return[m,[a].concat(j)]}return this[d]=h,this[c]=i,[b.length,b]}}function h(a){return g(a)&&a.length>1&&typeof a[1]=="object"&&!g(a[1])?a[1]:undefined}function i(a){var b=j(a),c={};for(var d=0;d<b.length;++d)if(/^#/.test(b[d]))c.id=b[d].substring(1);else if(/^\./.test(b[d]))c["class"]?c["class"]=c["class"]+b[d].replace(/./," "):c["class"]=b[d].substring(1);else if(/=/.test(b[d])){var e=b[d].split(/=/);c[e[0]]=e[1]}return c}function j(a){var b=a.split(""),c=[""],d=!1;while(b.length){var e=b.shift();switch(e){case" ":d?c[c.length-1]+=e:c.push("");break;case"'":case'"':d=!d;break;case"\\":e=b.shift();default:c[c.length-1]+=e}}return c}function k(a){return a.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;").replace(/'/g,"&#39;")}function l(a){if(typeof a=="string")return k(a);var b=a.shift(),c={},d=[];a.length&&typeof a[0]=="object"&&!(a[0]instanceof Array)&&(c=a.shift());while(a.length)d.push(arguments.callee(a.shift()));var e="";for(var f in c)e+=" "+f+'="'+k(c[f])+'"';return"<"+b+e+">"+d.join("")+"</"+b+">"}function m(a,b,c){c=c||{};var d=a.slice(0);typeof c.preprocessTreeNode=="function"&&(d=c.preprocessTreeNode(d,b));var e=h(d);if(e){d[1]={};for(var f in e)d[1][f]=e[f];e=d[1]}if(typeof d=="string")return d;switch(d[0]){case"header":d[0]="h"+d[1].level,delete d[1].level;break;case"bulletlist":d[0]="ul";break;case"numberlist":d[0]="ol";break;case"listitem":d[0]="li";break;case"para":d[0]="p";break;case"markdown":d[0]="html",e&&delete e.references;break;case"code_block":d[0]="pre";var f=e?2:1,g=["code"];g.push.apply(g,d.splice(f)),d[f]=g;break;case"inlinecode":d[0]="code";break;case"img":d[1].src=d[1].href,delete d[1].href;break;case"linebreak":d[0]="br";break;case"link":d[0]="a";break;case"link_ref":d[0]="a";var i=b[e.ref];if(i)delete e.ref,e.href=i.href,i.title&&(e.title=i.title),delete e.original;else return e.original}var f=1;if(e){for(var j in d[1])f=2;f===1&&d.splice(f,1)}for(;f<d.length;++f)d[f]=arguments.callee(d[f],b,c);return d}function n(a){var b=h(a)?2:1;while(b<a.length)typeof a[b]=="string"?b+1<a.length&&typeof a[b+1]=="string"?a[b]+=a.splice(b+1,1)[0]:++b:(arguments.callee(a[b]),++b)}var c=b.Markdown=function o(a){switch(typeof a){case"undefined":this.dialect=o.dialects.Gruber;break;case"object":this.dialect=a;break;default:if(a in o.dialects)this.dialect=o.dialects[a];else throw new Error("Unknown Markdown dialect '"+String(a)+"'")}this.em_state=[],this.strong_state=[],this.debug_indent=""};b.parse=function(a,b){var d=new c(b);return d.toTree(a)},b.toHTML=function(a,c,d){var e=b.toHTMLTree(a,c,d);return b.renderJsonML(e)},b.toHTMLTree=function(a,b,c){typeof a=="string"&&(a=this.parse(a,b));var d=h(a),e={};d&&d.references&&(e=d.references);var f=m(a,e,c);return n(f),f};var d=c.mk_block=function(a,b,c){arguments.length==1&&(b="\n\n");var d=new String(a);return d.trailing=b,d.toSource=function(){return"Markdown.mk_block( "+uneval(a)+", "+uneval(b)+", "+uneval(c)+" )"},c!=undefined&&(d.lineNumber=c),d};c.prototype.split_blocks=function(a,b){var c=/([\s\S]+?)($|\n(?:\s*\n|$)+)/g,f=[],g,h=1;(g=/^(\s*\n)/.exec(a))!=null&&(h+=e(g[0]),c.lastIndex=g[0].length);while((g=c.exec(a))!=null)f.push(d(g[1],g[2],h)),h+=e(g[0]);return f},c.prototype.processBlock=function(a,b){var c=this.dialect.block,d=c.__order__;if("__call__"in c)return c.__call__.call(this,a,b);for(var e=0;e<d.length;e++){var f=c[d[e]].call(this,a,b);if(f)return(!g(f)||f.length>0&&!g(f[0]))&&this.debug(d[e],"didn't return a proper array"),f}return[]},c.prototype.processInline=function(a){return this.dialect.inline.__call__.call(this,String(a))},c.prototype.toTree=function(a,b){var c=a instanceof Array?a:this.split_blocks(a),d=this.tree;try{this.tree=b||this.tree||["markdown"];c:while(c.length){var e=this.processBlock(c.shift(),c);if(!e.length)continue c;this.tree.push.apply(this.tree,e)}return this.tree}finally{b&&(this.tree=d)}},c.prototype.debug=function(){var a=Array.prototype.slice.call(arguments);a.unshift(this.debug_indent),typeof print!="undefined"&&print.apply(print,a),typeof console!="undefined"&&typeof console.log!="undefined"&&console.log.apply(null,a)},c.prototype.loop_re_over_block=function(a,b,c){var d,e=b.valueOf();while(e.length&&(d=a.exec(e))!=null)e=e.substr(d[0].length),c.call(this,d);return e},c.dialects={},c.dialects.Gruber={block:{atxHeader:function(a,b){var c=a.match(/^(#{1,6})\s*(.*?)\s*#*\s*(?:\n|$)/);if(!c)return undefined;var e=["header",{level:c[1].length}];return Array.prototype.push.apply(e,this.processInline(c[2])),c[0].length<a.length&&b.unshift(d(a.substr(c[0].length),a.trailing,a.lineNumber+2)),[e]},setextHeader:function(a,b){var c=a.match(/^(.*)\n([-=])\2\2+(?:\n|$)/);if(!c)return undefined;var e=c[2]==="="?1:2,f=["header",{level:e},c[1]];return c[0].length<a.length&&b.unshift(d(a.substr(c[0].length),a.trailing,a.lineNumber+2)),[f]},code:function(a,b){var c=[],e=/^(?: {0,3}\t| {4})(.*)\n?/,f,g=a.match(e);if(!g)return undefined;h:do{var i=this.loop_re_over_block(e,a.valueOf(),function(a){c.push(a[1])});if(i.length){b.unshift(d(i,a.trailing));break h}if(!b.length)break h;var g=b[0].match(e);if(!g)break h;c.push(a.trailing.replace(/[^\n]/g,"").substring(2)),a=b.shift()}while(!0);return[["code_block",c.join("\n")]]},horizRule:function(a,b){var c=a.match(/^(?:([\s\S]*?)\n)?[ \t]*([-_*])(?:[ \t]*\2){2,}[ \t]*(?:\n([\s\S]*))?$/);if(!c)return undefined;var e=[["hr"]];return c[1]&&e.unshift.apply(e,this.processBlock(c[1],[])),c[3]&&b.unshift(d(c[3])),e},lists:function(){function g(b){return new RegExp("(?:^("+f+"{0,"+b+"} {0,3})("+a+")\\s+)|"+"(^"+f+"{0,"+(b-1)+"}[ ]{0,4})")}function h(a){return a.replace(/ {0,3}\t/g,"    ")}function i(a,b,c,d){if(b){a.push(["para"].concat(c));return}var e=a[a.length-1]instanceof Array&&a[a.length-1][0]=="para"?a[a.length-1]:a;d&&a.length>1&&c.unshift(d);for(var f=0;f<c.length;f++){var g=c[f],h=typeof g=="string";h&&e.length>1&&typeof e[e.length-1]=="string"?e[e.length-1]+=g:e.push(g)}}function j(a,b){var c=new RegExp("^("+f+"{"+a+"}.*?\\n?)*$"),e=new RegExp("^"+f+"{"+a+"}","gm"),g=[];while(b.length>0){if(c.exec(b[0])){var h=b.shift(),i=h.replace(e,"");g.push(d(i,h.trailing,h.lineNumber))}break}return g}function k(a,b,c){var d=a.list,e=d[d.length-1];if(e[1]instanceof Array&&e[1][0]=="para")return;if(b+1==c.length)e.push(["para"].concat(e.splice(1)));else{var f=e.pop();e.push(["para"].concat(e.splice(1)),f)}}var a="[*+-]|\\d\\.",b=/[*+-]/,c=/\d+\./,e=new RegExp("^( {0,3})("+a+")[ \t]+"),f="(?: {0,3}\\t| {4})";return function(a,c){function f(a){var c=b.exec(a[2])?["bulletlist"]:["numberlist"];return l.push({list:c,indent:a[1]}),c}var d=a.match(e);if(!d)return undefined;var l=[],m=f(d),n,o=!1,p=[l[0].list];q:for(;;){var r=a.split(/(?=\n)/),s="";t:for(var u=0;u<r.length;u++){var v="",w=r[u].replace(/^\n/,function(a){return v=a,""}),x=g(l.length);d=w.match(x);if(d[1]!==undefined){s.length&&(i(n,o,this.processInline(s),v),o=!1,s=""),d[1]=h(d[1]);var y=Math.floor(d[1].length/4)+1;if(y>l.length)m=f(d),n.push(m),n=m[1]=["listitem"];else{var z=l.some(function(a,b){return a.indent!=d[1]?!1:(m=a.list,l.splice(b+1),!0)});z||(y++,y>l.length?(m=f(d),n.push(m)):(l.splice(y),m=l[y-1].list)),n=["listitem"],m.push(n)}v=""}w.length>d[0].length&&(s+=v+w.substr(d[0].length))}s.length&&(i(n,o,this.processInline(s),v),o=!1,s="");var A=j(l.length,c);A.length>0&&(l.forEach(k,this),n.push.apply(n,this.toTree(A,[])));var B=c[0]&&c[0].valueOf()||"";if(B.match(e)||B.match(/^ /)){a=c.shift();var C=this.dialect.block.horizRule(a,c);if(C){p.push.apply(p,C);break}l.forEach(k,this),o=!0;continue q}break}return p}}(),blockquote:function(a,b){if(!a.match(/^>/m))return undefined;var c=[];if(a[0]!=">"){var d=a.split(/\n/),e=[];while(d.length&&d[0][0]!=">")e.push(d.shift());a=d.join("\n"),c.push.apply(c,this.processBlock(e.join("\n"),[]))}while(b.length&&b[0][0]==">"){var f=b.shift();a+=a.trailing+f,a.trailing=f.trailing}var g=a.replace(/^> ?/gm,""),h=this.tree;return c.push(this.toTree(g,["blockquote"])),c},referenceDefn:function(a,b){var c=/^\s*\[(.*?)\]:\s*(\S+)(?:\s+(?:(['"])(.*?)\3|$(.*?)$))?\n?/;if(!a.match(c))return undefined;h(this.tree)||this.tree.splice(1,0,{});var e=h(this.tree);e.references===undefined&&(e.references={});var f=this.loop_re_over_block(c,a,function(a){a[2]&&a[2][0]=="<"&&a[2][a[2].length-1]==">"&&(a[2]=a[2].substring(1,a[2].length-1));var b=e.references[a[1].toLowerCase()]={href:a[2]};a[4]!==undefined?b.title=a[4]:a[5]!==undefined&&(b.title=a[5])});return f.length&&b.unshift(d(f,a.trailing)),[]},para:function(a,b){return[["para"].concat(this.processInline(a))]}}},c.dialects.Gruber.inline={__call__:function(a,b){function g(a){typeof a=="string"&&typeof c[c.length-1]=="string"?c[c.length-1]+=a:c.push(a)}var c=[],d,e=new RegExp("([\\s\\S]*?)("+(b.source||b)+")","g"),f=0;while((d=e.exec(a))!=null){d[1]?g(d[1]):d[1]={length:0};var h;d[2]in this.dialect.inline&&(h=this.dialect.inline[d[2]].call(this,a.substr(d.index+d[1].length),d,c)),h=h||[d[2].length,d[2]];var i=h.shift();e.lastIndex+=i-d[2].length,h.forEach(g),f=e.lastIndex}return a.length>f&&g(a.substr(f)),c},"\\":function(a){return a.match(/^\\[\\`\*_{}\[\]()#\+.!\-]/)?[2,a[1]]:[1,"\\"]},"![":function(a){var b=a.match(/^!\[(.*?)\][ \t]*$[ \t]*(\S*)(?:[ \t]+(["'])(.*?)\3)?[ \t]*$/);if(b){b[2]&&b[2][0]=="<"&&b[2][b[2].length-1]==">"&&(b[2]=b[2].substring(1,b[2].length-1)),b[2]==this.dialect.inline.__call__.call(this,b[2],/\\/)[0];var c={alt:b[1],href:b[2]||""};return b[4]!==undefined&&(c.title=b[4]),[b[0].length,["img",c]]}return b=a.match(/^!\[(.*?)\][ \t]*\[(.*?)\]/),b?[b[0].length,["img_ref",{alt:b[1],ref:b[2].toLowerCase(),text:b[0]}]]:[2,"!["]},"[":function G(a){var b=a.match(/^\[([\s\S]*?)\][ \t]*$[ \t]*(\S+)(?:[ \t]+(["'])(.*?)\3)?[ \t]*$/);if(b){b[2]&&b[2][0]=="<"&&b[2][b[2].length-1]==">"&&(b[2]=b[2].substring(1,b[2].length-1)),b[2]=this.dialect.inline.__call__.call(this,b[2],/\\/)[0];var c={href:b[2]||""};b[4]!==undefined&&(c.title=b[4]);var G=["link",c];return Array.prototype.push.apply(G,this.processInline(b[1])),[b[0].length,G]}b=a.match(/^\[([\s\S]*?)\](?: ?\[(.*?)\])?/);if(b){if(b[2]===undefined||b[2]==="")b[2]=b[1];return c={ref:b[2].toLowerCase(),original:b[0]},G=["link_ref",c],Array.prototype.push.apply(G,this.processInline(b[1])),[b[0].length,G]}return[1,"["]},"<":function(a){var b;return(b=a.match(/^<(?:((https?|ftp|mailto):[^>]+)|(.*?@.*?\.[a-zA-Z]+))>/))!=null?b[3]?[b[0].length,["link",{href:"mailto:"+b[3]},b[3]]]:b[2]=="mailto"?[b[0].length,["link",{href:b[1]},b[1].substr("mailto:".length)]]:[b[0].length,["link",{href:b[1]},b[1]]]:[1,"<"]},"`":function(a){var b=a.match(/(`+)(([\s\S]*?)\1)/);return b&&b[2]?[b[1].length+b[2].length,["inlinecode",b[3]]]:[1,"`"]},"  \n":function(a){return[3,["linebreak"]]}},c.dialects.Gruber.inline["**"]=f("strong","**"),c.dialects.Gruber.inline.__=f("strong","__"),c.dialects.Gruber.inline["*"]=f("em","*"),c.dialects.Gruber.inline._=f("em","_"),c.buildBlockOrder=function(a){var b=[];for(var c in a){if(c=="__order__"||c=="__call__")continue;b.push(c)}a.__order__=b},c.buildInlinePatterns=function(a){var b=[];for(var c in a){if(c=="__call__")continue;var d=c.replace(/([\\.*+?|()\[\]{}])/g,"\\$1").replace(/\n/,"\\n");b.push(c.length==1?d:"(?:"+d+")")}b=b.join("|");var e=a.__call__;a.__call__=function(a,c){return c!=undefined?e.call(this,a,c):e.call(this,a,b)}},c.subclassDialect=function(a){function b(){}function c(){}return b.prototype=a.block,c.prototype=a.inline,{block:new b,inline:new c}},c.buildBlockOrder(c.dialects.Gruber.block),c.buildInlinePatterns(c.dialects.Gruber.inline),c.dialects.Maruku=c.subclassDialect(c.dialects.Gruber),c.dialects.Maruku.block.document_meta=function(a,b){if(a.lineNumber>1)return undefined;if(!a.match(/^(?:\w+:.*\n)*\w+:.*$/))return undefined;h(this.tree)||this.tree.splice(1,0,{});var c=a.split(/\n/);for(p in c){var d=c[p].match(/(\w+):\s*(.*)$/),e=d[1].toLowerCase(),f=d[2];this.tree[1][e]=f}return[]},c.dialects.Maruku.block.block_meta=function(b,c){var d=b.match(/(^|\n) {0,3}\{:\s*((?:\\\}|[^\}])*)\s*\}$/);if(!d)return undefined;var e=i(d[2]);if(d[1]===""){var f=this.tree[this.tree.length-1],g=h(f);if(typeof f=="string")return undefined;g||(g={},f.splice(1,0,g));for(a in e)g[a]=e[a];return[]}var j=b.replace(/\n.*$/,""),k=this.processBlock(j,[]),g=h(k[0]);g||(g={},k[0].splice(1,0,g));for(a in e)g[a]=e[a];return k},c.dialects.Maruku.block.definition_list=function(a,b){var c=/^((?:[^\s:].*\n)+):\s+([^]+)$/,d=["dl"];if(!(g=a.match(c)))return undefined;var e=[a];while(b.length&&c.exec(b[0]))e.push(b.shift());for(var f=0;f<e.length;++f){var g=e[f].match(c),h=g[1].replace(/\n$/,"").split(/\n/),i=g[2].split(/\n:\s+/);for(var j=0;j<h.length;++j)d.push(["dt",h[j]]);for(var j=0;j<i.length;++j)d.push(["dd"].concat(this.processInline(i[j].replace(/(\n)\s+/,"$1"))))}return[d]},c.dialects.Maruku.inline["{:"]=function(a,b,c){if(!c.length)return[2,"{:"];var d=c[c.length-1];if(typeof d=="string")return[2,"{:"];var e=a.match(/^\{:\s*((?:\\\}|[^\}])*)\s*\}/);if(!e)return[2,"{:"];var f=i(e[1]),g=h(d);g||(g={},d.splice(1,0,g));for(var j in f)g[j]=f[j];return[e[0].length,""]},c.buildBlockOrder(c.dialects.Maruku.block),c.buildInlinePatterns(c.dialects.Maruku.inline);var g=b.isArray=function(a){return a instanceof Array||typeof a=="array"||Array.isArray(a)};b.renderJsonML=function(a,b){b=b||{},b.root=b.root||!1;var c=[];if(b.root)c.push(l(a));else{a.shift(),a.length&&typeof a[0]=="object"&&!(a[0]instanceof Array)&&a.shift();while(a.length)c.push(l(a.shift()))}return c.join("\n\n")}})(function(){return typeof exports=="undefined"?(window.markdown={},window.markdown):exports}());

//works in modern browsers
var request = new XMLHttpRequest();
request.open('GET', './README.md', false);
request.send(null);
if (request.status == 200) {
  document.getElementById("markdown").innerHTML = markdown.toHTML(request.responseText);
}
</script>
</body>
</html>