How can I test what my readme.md file will look like before committing to github?
GithubMarkdownGithub Flavored-MarkdownGithub Problem Overview
I am writing a readme for my github project in the .md format. Is there a way can I test what my readme.md file will look like before committing to github?
Github Solutions
Solution 1 - Github
Many ways: If you're on a Mac, use Mou.
If you want to test in a browser, you could try StackEdit, as pointed out by @Aaron or Dillinger since Notepag seems to be down now. Personally I use Dillinger since it just works and saves all my documents in my browser's local database.
Solution 2 - Github
Atom works nicely out of the box - just open the Markdown file and hit Ctrl+Shift+M to toggle the Markdown preview panel next to it. It handles HTML and images also.
Solution 3 - Github
Visual Studio Code has the option to edit and preview md file changes. Since VS Code is platform independent, this would work for Windows, Mac and Linux.
> To switch between views, press Ctrl+Shift+V in the editor. You can view the preview side-by-side (Ctrl+K V) with the file you are editing and see changes reflected in real-time as you edit.
Also...
> Q: Does VS Code support GitHub Flavored Markdown? > > A: No, VS Code targets the CommonMark Markdown specification using the markdown-it library. GitHub is moving toward the CommonMark specification.
The preview button is this: 
Solution 4 - Github
This is a pretty old question, however since I stumbled upon it while searching the internet maybe my answer is useful to others. I just found a very useful CLI tool for rendering GitHub flavored markdown: [grip][1]. It uses GitHub's API, thus renders quite well.
Frankly, the developer of [grip][1], has a more elaborate answer on these very similar questions:
- https://stackoverflow.com/questions/7694887/is-there-a-command-line-utility-for-rendering-github-flavored-markdown
- https://stackoverflow.com/questions/10871865/whats-the-best-way-to-edit-githubs-readme-md
[1]: https://github.com/joeyespo/grip "Grip (GitHub Readme Instant Preview)"
Solution 5 - Github
This one has proven reliable for quite some time: http://tmpvar.com/markdown.html
Solution 6 - Github
I usually just edit it on the GitHub website directly and click "Preview" just above the editing window.
Perhaps that's a new feature that's been added since this post was made.
Solution 7 - Github
In the web, use Dillinger. It's awesome.
Solution 8 - Github
I use a locally hosted HTML file to preview GitHub readmes.
I looked at several existing options, but decided to roll my own to meet the following requirements:
- Single file
- Locally hosted (intranet) URL
- No browser extension required
- No locally hosted server-side processing (for example, no PHP)
- Lightweight (for example, no jQuery)
- High fidelity: use GitHub to render the Markdown, and same CSS
I keep local copies of my GitHub repositories in sibling directories under a "github" directory.
Each repo directory contains a README.md file:
.../github/
repo-a/
README.md
repo-b/
README.md
etc.
The github directory contains the "preview" HTML file:
.../github/
readme.html
To preview a readme, I browse github/readme.html, specifying the repo in the query string:
http://localhost/github/readme.html?repo-a
Alternatively, you can copy the readme.html into the same directory as the README.md, and omit the query string:
http://localhost/github/repo-a/readme.html
If the readme.html is in the same directory as README.md, you don't even need to serve readme.html over HTTP: you can just open it directly from your file system.
The HTML file uses the GitHub API to render the Markdown in a README.md file. There's a rate limit: at the time of writing, 60 requests per hour.
Works for me in current production versions of Chrome, IE, and Firefox on Windows 7.
Source
Here's the HTML file (readme.html):
<!DOCTYPE html>
<!--
Preview a GitHub README.md.
Either:
- Copy this file to a directory that contains repo directories,
and then specify a repo name in the query string.
For example:
http://localhost/github/readme.html?myrepo
or
- Copy this file to the directory that contains a README.md,
and then browse to this file without specifying a query string.
For example:
http://localhost/github/myrepo/readme.html
(or just open this file in your browser directly from
your file system, without HTTP)
-->
<html lang="en">
<head>
<meta charset="utf-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta name="author" content="Graham Hannington"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GitHub readme preview</title>
<link rel="stylesheet" type="text/css" href="http://primercss.io/docs.css"/>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";
var readmeURL;
var queryString = location.search.substring(1);
if (queryString.length > 0) {
readmeURL = queryString + "/" + README_FILE_NAME;
} else {
readmeURL = README_FILE_NAME;
}
// Get Markdown, then render it as HTML
function getThenRenderMarkdown(markdownURL) {
var xhr = new XMLHttpRequest();
xhr.open("GET", markdownURL, true);
xhr.responseType = "text";
xhr.onload = function(e) {
if (this.status == HTTP_STATUS_OK) {
// Response text contains Markdown
renderMarkdown(this.responseText);
}
}
xhr.send();
}
// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) {
var xhr = new XMLHttpRequest();
xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
xhr.responseType = "html";
xhr.onload = function(e) {
if (this.status == HTTP_STATUS_OK) {
document.getElementById("readme").innerHTML = this.response;
}
}
xhr.send(markdown);
}
window.onload = function() {
getThenRenderMarkdown(readmeURL);
}
//]]>
</script>
</head>
<body>
<header class="masthead">
<div class="container">
<span class="masthead-logo"><span class="mega-octicon
octicon-mark-github"></span>GitHub readme preview</span>
</div>
</header>
<div class="container">
<div id="readme" class="markdown-body">
<p>Rendering markdown, please wait...</p>
</div>
<footer class="footer">Rendering by
<a href="https://developer.github.com/v3/markdown/">GitHub</a>,
styling by <a href="http://primercss.io/">Primer</a>.</footer>
</div>
</body>
</html>
Developer notes
- Typically, I wrap my code in an IIFE, but in this case, I didn't see the need, and thought I'd keep it concise
- I haven't bothered supporting backlevel IE
- For conciseness, I have omitted the error handling code (do you believe me?!)
- I'd welcome JavaScript programming tips
Ideas
- I'm considering creating a GitHub repository for this HTML file, and putting the file in the gh-pages branch, so that GitHub serves it as a "normal" web page. I'd tweak the file to accept a complete URL - of the README (or any other Markdown file) - as the query string. I'm curious to see whether being hosted by GitHub would sidestep the GitHub API request limit, and whether I run afoul of cross-domain issues (using an Ajax request to get the Markdown from a different domain than the domain serving the HTML page).
Original version (deprecated)
I've preserved this record of the original version for curiosity value. This version had the following issues that are solved in the current version:
- It required some related files to be downloaded
- It didn't support being dropped into the same directory as the README.md
- Its HTML was more brittle; more susceptible to changes in GitHub
The github directory contains the "preview" HTML file and related files:
.../github/
readme-preview.html
github.css
github2.css
octicons.eot
octicons.svg
octicons.woff
I downloaded the CSS and octicons font files from GitHub:
https://assets-cdn.github.com/assets/github- ... .css
https://assets-cdn.github.com/assets/github2- ... .css
https://github.com/static/fonts/octicons/octicons.* (eot, woff, svg)
I renamed the CSS files to omit the long string of hex digits in the original names.
I edited github.css to refer to the local copies of the octicons font files.
I examined the HTML of a GitHub page, and reproduced enough of the HTML structure surrounding the readme content to provide reasonable fidelity; for example, the constrained width.
The GitHub CSS, octicons font, and HTML "container" for the readme content are moving targets: I will need to periodically download new versions.
I toyed with using CSS from various GitHub projects. For example:
<link rel="stylesheet" type="text/css"
href="http://rawgit.com/sindresorhus/github-markdown-css/gh-pages/github-markdown.css">
but eventually decided to use the CSS from GitHub itself.
Source
Here's the HTML file (readme-preview.html):
<!DOCTYPE html>
<!-- Preview a GitHub README.md.
Copy this file to a directory that contains repo directories.
Specify a repo name in the query string. For example:
http://localhost/github/readme-preview.html?myrepo
-->
<html>
<head>
<title>Preview GitHub readme</title>
<meta http-equiv="X-UA-Compatible" content="IE=Edge"/>
<meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
<!-- Downloaded copies of the CSS files served by GitHub.
In github.css, the @font-face for font-family:'octicons'
has been edited to refer to local copies of the font files -->
<link rel="stylesheet" type="text/css" href="github.css"/>
<link rel="stylesheet" type="text/css" href="github2.css"/>
<style>
body {
margin-top: 1em;
}
</style>
<script type="text/javascript">
//<![CDATA[
var HTTP_STATUS_OK = 200;
var URL_API_GITHUB_RENDER_MARKDOWN = "https://api.github.com/markdown/raw";
var README_FILE_NAME = "README.md";
var repo = location.search.substring(1);
// Get Markdown, then render it as HTML
function getThenRenderMarkdown() {
var xhr = new XMLHttpRequest();
xhr.open("GET", repo + "/" + README_FILE_NAME, true);
xhr.responseType = "text";
xhr.onload = function(e) {
if (this.status == HTTP_STATUS_OK) {
// Response text contains Markdown
renderMarkdown(this.responseText);
}
}
xhr.send();
}
// Use the GitHub API to render Markdown as HTML
function renderMarkdown(markdown) {
var xhr = new XMLHttpRequest();
xhr.open("POST", URL_API_GITHUB_RENDER_MARKDOWN, true);
xhr.responseType = "html";
xhr.onload = function(e) {
if (this.status == HTTP_STATUS_OK) {
document.getElementById("readme-content").innerHTML = this.response;
}
}
xhr.send(markdown);
}
window.onload = getThenRenderMarkdown;
//]]>
</script>
</head>
<body>
<!-- The following HTML structure was copied from live GitHub page on 2015-12-01,
except for the "readme-content" id of the article element,
which was coined for this preview page.-->
<div class="main-content" role="main">
<div class="container repo-container new-discussion-timeline experiment-repo-nav">
<div class="repository-content">
<div id="readme" class="boxed-group flush clearfix announce instapaper_body md">
<h3><span class="octicon octicon-book"></span>README.md</h3>
<article class="markdown-body entry-content"
itemprop="mainContentOfPage"
id="readme-content"><p>Rendering markdown...</p></article>
</div>
</div>
</div>
</div>
</body>
</html>
Solution 9 - Github
For Visual Studio users (not VS CODE).
Install Markdown Editor extension
This way, when you open a README.md you'll have a live preview on right side.
Solution 10 - Github
You may want to take a look at this one:
Solution 11 - Github
For Github or Bitbucket theme, could use online editor mattstow, url: http://writeme.mattstow.com
Solution 12 - Github
Just searching the web gives many heres one: https://stackedit.io/
Solution 13 - Github
SublimeText 2/3
Install package: Markdown Preview
Options:
- Preview in browser.
- Export to html.
- Copy to clipboard.
Solution 14 - Github
MarkdownPreview, the plugin for Sublime Text mentioned in an earlier comment is not compatible with ST2 any more, but only supports Sublime Text 3 (since spring 2018).
What's neat about it: it supports GFM, GitHub Flavored Markdown, which can do a bit more than regular Markdown. This is of relevance if you want to know what your .mds will look like on GH exactly. (Including this bit of info because the OP didn't add the GFM tag themselves, and others looking for a solution might not be aware of it either.)
You can use it with the GitHub API if you are online, though you should get a personal access token for this purpose because API calls without authentication are limited. There's more info on Parsing GFM in the plugin's docs.
Solution 15 - Github
I am using markdownlivepreview:
https://markdownlivepreview.com/
It is very easy, simple and fast.
Solution 16 - Github
Since 2012 (when this question was created) GitHub itself can:
- create and display a preview of a Markdown document in a regular repository (it always did, since Aug. 2011)
- or, if you don't want to impact directly your repository, do the same with gist (since Dec. 2020)
Even without committing a gist, you can, since Nov. 2021, preview a Markdown document in a Gist you are editing (but not yet committing)
Once the preview of that gist looks good, you can copy the markdown from said gist to your local README.md, add, commit and push.
Solution 17 - Github
If you're using Pycharm (or another Jetbrains IDE like Intellij, RubyMine, PHPStorm, etc), there are multiple free plugins for Markdown support right in your IDE that allow real-time preview while editing. The Markdown Navigator plugin is quite good. If you open an .md file in the IDE, recent versions will offer to install supporting plugins and show you the list.
Solution 18 - Github
Use Jupyter Lab.
To install Jupyter Lab, type the following in your environment:
pip install jupyterlab
After installation, browse to the location of your markdown file, right-click the file, select "Open With" then click "Markdown Preview".
Solution 19 - Github
For Visual Studio Code, I use
> Markdown Preview Enhanced extension.
Solution 20 - Github
I know this question is old perhaps someone was googling how to and reached here. That is how I saw this question anyway.
You can use atom text editor and toggle markdown preview even in github style.
Press
ctrl+shift+m
The window will pop up or use Packages-->Markdown Preview.
Hope this helps someone.
Solution 21 - Github
One way is using the Pandoc (very useful).
-
Copy your Markdown plaint text to clipboard
-
Run:
xsel -b | pandoc -s -f markdown -t html | xclip -selection clipboard -t text/html | xsel -b -
Paste the generated formatted text (for example on an email or LibreOffice).
You said you are using Linux. You'll need to just install pandoc, xsel and xclip packages.
Solution 22 - Github
VS Code
Mac: Command + Shift + V
Windows: Ctrl + Shift + V
Detailed Instructions
Open the .md file in VS Code. With the file selected, use the keyboard shortcuts above.
Solution 23 - Github
MarkdownViewerPlusPlus is a "[...]Notepad++ Plugin to view a Markdown file rendered on-the-fly Features
-
Dockable panel (toggle) with a rendered HTML of the currently selected file/tab
-
CommonMark compliant (0.28)
-
Synchronized scrolling
-
Custom CSS integration
-
HTML and PDF Export
-
Notepad++ Unicode Plugin [...]"
Solution 24 - Github
You could use the static site editor: with GitLab 13.0 (May 2020), it comes with a WYSIWYG panel.
> ## WYSIWYG for the Static Site Editor
>
> Markdown is a powerful and efficient syntax for authoring web content, but even seasoned authors of Markdown content can struggle to remember some of the less-frequently used formatting options or write even moderately-complex tables from scratch.
There are some jobs better accomplished with a rich text, “What You See Is What You Get” (WYSIWYG) editor.
>
> GitLab 13.0 brings a WYSIWYG Markdown authoring experience to the Static Site Editor with formatting options for common formatting options like headers, bold, italics, links, lists, blockquotes, and code blocks.
>
> 
>
> The WYSIWYG editor also removes the onerous task of editing tables in Markdown by letting you visually edit table rows, columns and cells in the same way you would edit a spreadsheet. For those more comfortable writing in raw Markdown, there’s even a tab for switching between WYSIWYG and plain text editing modes.
See documentation and issue.
Again, you would use it only to write your README: once it looks good, you can report it back to your original project.
But the point is: you don't need no more any thrid-party markdown preview plugin.
And with GitLab 14.2 (August 2021)
> ## Preview Markdown live while editing
>
> Markdown is a fast and intuitive syntax for writing rich web content. Until it isn’t.
Luckily, it’s easy to preview the rendered output of Markdown to ensure the accuracy of your markup from the Preview tab.
>
> Unfortunately, the context switch required to move between the raw source code and the preview can be tedious and disruptive to your flow.
>
> Now, in both the Web IDE and single file editor, Markdown files have a new live preview option available. Right-click the editor and select Preview Markdown or use Command/Control + Shift + P to toggle a split-screen live preview of your Markdown content.
The preview refreshes as you type, so you can be confident that your markup is valid and will render as you intended.
>
> 
>
> See Documentation and Epic.
See GitLab 14.6 (December 2021)
> ## Toggle wiki editors seamlessly
>
> Toggle wiki editors seamlessly
>
> Editing wiki pages with the new rich Markdown editor makes it easier for everyone to contribute regardless of how well they know Markdown syntax.
You may also prefer to write raw Markdown in some situations, but use the WYSIWYG interface for more complex or tedious formatting tasks, like creating tables.
>
> Previous versions of GitLab required you to save changes before switching between the rich Markdown editor and the Markdown source, adding more steps and friction to your edits.
>
> In GitLab 14.6 you can now seamlessly switch between the two editing experiences without committing your changes, choosing the editor that suits your needs at any given moment.
>
> See Documentation and Issue.
Solution 25 - Github
I have found that markdownlivepreview.com is pretty close to vanilla GitLab markdown. Other viewers interpreted commands slightly differently than GitLab does.
Solution 26 - Github
I just create a "feature" branch and push it to github where I make changes, which become visible exactly how they will look in github.
Then, when I'm satisfied, I rebase back to main or do a pull request to main, whichever process you happen to be using.
You rarely need to test locally when using git, unless your repository is behind a corp firewall, or need to work offline.
In such cases, both Atom and VScode have decent Markdown renderers, not good enough to show how your changes will look on github, but good enough to see if your changes are going in the right direction.
Solution 27 - Github
For those who wish to develop on their iPads, I like Textastic. You can edit and preview the README.md files without an internet connection, once you have downloaded the document from the cloud.